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 |
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.
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
-
+ 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: -
+ imageWithIOSurface: -
+ imageWithIOSurface:options:
Creating an Image by Modifying an Existing Image
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: -
– initWithIOSurface: -
– initWithIOSurface:options:
Getting Image Information
Class Methods
emptyImage
Creates and returns an empty image object.
Return Value
An image object.
Availability
- Available in OS X v10.5 and later.
Declared In
CIImage.himageWithBitmapData:bytesPerRow:size:format:colorSpace:
Creates and returns an image object from bitmap data.
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. Passnilfor 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.himageWithCGImage:
Creates and returns an image object from a Quartz 2D 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.
Declared In
CIImage.himageWithCGImage:options:
Creates and returns an image object from a Quartz 2D image using the specified color space.
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 aCGColorSpaceobject. (SeeCGColorSpaceRef.)
Return Value
An image object initialized with the contents of the Quartz 2D image and the specified color space.
Availability
- Available in OS X v10.4 and later.
Declared In
CIImage.himageWithCGLayer:
Creates and returns an image object from the contents supplied by a CGLayer object.
Parameters
- layer
A
CGLayerobject. 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.himageWithCGLayer:options:
Creates and returns an image object from the contents supplied by a CGLayer object, using the specified options.
Parameters
- layer
A
CGLayerobject. 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” and “Color Space Key.”
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.himageWithColor:
Creates and returns an image of infinite extent that is initialized the specified 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.
See Also
Declared In
CIImage.himageWithContentsOfURL:
Creates and returns an image object from the contents of a file.
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.himageWithContentsOfURL:options:
Creates and returns an image object from the contents of a file, using the specified options.
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” and “Color Space Key.”
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.himageWithCVImageBuffer:
Creates and returns an image object from the contents of CVImageBuffer object.
Parameters
- imageBuffer
A
CVImageBufferobject. 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.himageWithCVImageBuffer:options:
Creates and returns an image object from the contents of CVImageBuffer object, using the specified options.
Parameters
- imageBuffer
A
CVImageBufferobject. For more information, see Core Video Programming Guide and Core Video Reference Collection.- 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
CVImageBufferobject.) See “Color Space Key.”
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.himageWithData:
Creates and returns an image object initialized with the supplied image 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.
See Also
Declared In
CIImage.himageWithData:options:
Creates and returns an image object initialized with the supplied image data, using the specified options.
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” and “Color Space Key.”
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.
See Also
Declared In
CIImage.himageWithImageProvider:size:format:colorSpace:options:
Creates and returns an image object initialized with data provided by an image provider.
Parameters
- p
A data provider that implements the
CIImageProviderinformal 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. Passnilfor 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
kCIImageProviderTileSizeorkCIImageProviderUserInfo. 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.
Declared In
CIImageProvider.himageWithIOSurface:
Creates and returns an image from the contents of an IOSurface.
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.himageWithIOSurface:options:
Creates, using the specified options, and returns an image from the contents of an IOSurface.
Parameters
- surface
An IOSurface object.
- options
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” and “Color Space Key.”
Return Value
An image object initialized with the data from the IOSurface.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
CIImage.himageWithTexture:size:flipped:colorSpace:
Creates and returns an image object initialized with data supplied by an OpenGL texture.
Parameters
- name
An OpenGL texture. Because
CIImageobjects 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
YESto 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
colorSpacevalue isnil, the image is not color matched. Passnilfor 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
CGLContextobject that theCIContextis based on.The context that the texture was created in must be shared with the
CGLContextthat theCIContextis 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.hInstance Methods
definition
Returns a filter shape object that represents the domain of definition of the image.
Return Value
A filter shape object.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
CIImage.hextent
Returns a rectangle that specifies the extent of the image.
Return Value
A rectangle that specifies the extent of the image in working space coordinates.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
CIImage.himageByApplyingTransform:
Returns a new image that represents the original image after applying an affine transform.
Parameters
- matrix
An affine transform.
Return Value
The transformed image object.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
CIImage.himageByCroppingToRect:
Returns a new image that represents the original image after cropping to a rectangle.
Return Value
An image object cropped to the specified rectangle.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
CIImage.hinitWithBitmapData:bytesPerRow:size:format:colorSpace:
Initializes an image object with bitmap data.
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). Passnilfor 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.hinitWithCGImage:
Initializes an image object with a Quartz 2D 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.hinitWithCGImage:options:
Initializes an image object with a Quartz 2D image, using the specified options.
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”and “Color Space Key.”
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.hinitWithCGLayer:
Initializes an image object from the contents supplied by a CGLayer object.
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.
Declared In
CIImage.hinitWithCGLayer:options:
Initializes an image object from the contents supplied by a CGLayer object, using the specified options.
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
- Available in OS X v10.4 and later.
Declared In
CIImage.hinitWithColor:
Initializes an image with the specified 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.
See Also
Declared In
CIImage.hinitWithContentsOfURL:
Initializes an image object by reading an image from a 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.hinitWithContentsOfURL:options:
Initializes an image object by reading an image from a URL, using the specified options.
Parameters
- url
The location of the image file to read.
- 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
- Available in OS X v10.4 and later.
Declared In
CIImage.hinitWithCVImageBuffer:
Initializes an image object from the contents of CVImageBuffer object.
Parameters
- imageBuffer
A
CVImageBufferobject 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.
Declared In
CIImage.hinitWithCVImageBuffer:options:
Initializes an image object from the contents of CVImageBuffer object, using the specified options.
Parameters
- imageBuffer
A
CVImageBufferobject 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. You can supply such options as a color space. (The pixel format is supplied by the
CVImageBufferobject.)
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.hinitWithData:
Initializes an image object with the supplied image 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.
See Also
Declared In
CIImage.hinitWithData:options:
Initializes an image object with the supplied image data, using the specified options.
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
- Available in OS X v10.4 and later.
See Also
Declared In
CIImage.hinitWithImageProvider:size:format:colorSpace:options:
Initializes an image object with data provided by an image provider, using the specified options.
Parameters
- p
A data provider that implements the
CIImageProviderinformal 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. Passnilfor 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
kCIImageProviderTileSizeorkCIImageProviderUserInfo. 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.
Declared In
CIImageProvider.hinitWithIOSurface:
Initializes an image with the contents of an IOSurface.
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.hinitWithIOSurface:options:
Initializes, using the specified options, an image with the contents of an IOSurface.
Parameters
- surface
An IOSurface object.
- options
An options dictionary.
Return Value
An image object initialized with the data from the IOSurface.
Availability
- Available in OS X v10.6 and later.
Declared In
CIImage.hinitWithTexture:size:flipped:colorSpace:
Initializes an image object with data supplied by an OpenGL texture.
Parameters
- name
An OpenGL texture. Because
CIImageobjects 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
YESto 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 thecolorSpacevalue isnil, the image is not color matched. Passnilfor 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
CGLContextobject that theCIContextis based on.The context that the texture was created in must be shared with the
CGLContextthat theCIContextis 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.hConstants
Pixel Formats
Image data pixel formats.
extern CIFormat kCIFormatARGB8; extern CIFormat kCIFormatRGBA16; extern CIFormat kCIFormatRGBAf; extern CIFormat kCIFormatRGBAh;
Constants
CIFormatThe data type for a pixel format.
kCIFormatARGB8A 32 bit-per-pixel, fixed-point pixel format.
kCIFormatRGBA16A 64 bit-per-pixel, fixed-point pixel format.
kCIFormatRGBAfA 128 bit-per-pixel, floating-point pixel format.
kCIFormatRGBAhA 64 bit-per-pixel, floating-point pixel format.
Declared In
CIImage.hColor Space Key
A key for the color space of an image.
extern NSString *kCIImageColorSpace;
Constants
kCIImageColorSpaceThe key for a color space. The value you supply for this dictionary key must be a
CGColorSpaceRefdata 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© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)