CIFilter Class Reference

Inherits from	NSObject
Conforms to	NSCoding NSCopying NSObject (NSObject)
Framework	Library/Frameworks/CoreImage.framework
Availability	Available in iOS 5.0 and later.
Declared in	CIFilter.h
Companion guides	Core Image Programming Guide Image Unit Tutorial Core Image Filter Reference
Related sample code	PocketCoreImage

Overview

The CIFilter class produces a CIImage object as output. Typically, a filter takes one or more images as input. Some filters, however, generate an image based on other types of input parameters. The parameters of a CIFilter object are set and retrieved through the use of key-value pairs.

You use the CIFilter object in conjunction with other Core Image classes, such as CIImage, CIContext, and CIColor, to take advantage of the built-in Core Image filters when processing images, creating filter generators, or writing custom filters.

CIFilter objects, are not mutable. A CIFilter object cannot be shared safely among threads. If you app is multithreaded, each thread must create its own CIFilter object. Otherwise, your app could behave unexpectedly.

To get a quick overview of how to set up and use Core Image filters, see Core Image Programming Guide.

Subclassing Notes

You can subclass CIFilter in order to create:

A filter by chaining together two or more built-in Core Image filters (iOS and OS X)
A custom filter that uses an image processing kernel that you write (OS X only)

See Core Image Programming Guide for details.

Tasks

Creating a Filter

Accessing Registered Filters

Getting Filter Parameters and Attributes

Setting Default Values

Serializing and Deserializing Filters

Properties

outputImage

Returns a CIImage object that encapsulates the operations configured in the filter. (read-only)

@property(readonly, nonatomic) CIImage *outputImage

Availability

Available in iOS 5.0 and later.

Declared In

CIFilter.h

Class Methods

filterArrayFromSerializedXMP:inputImageExtent:error:

Returns an array of filter objects de-serialized from XMP data.

+ (NSArray*)filterArrayFromSerializedXMP:(NSData *)xmpData inputImageExtent:(CGRect)extent error:(NSError **)outError

Parameters

xmpData: The XMP data created previously by calling serializedXMPFromFilters:inputImageExtent:.
extent: The extent of the image from which the XMP data was extracted.
outError: The address of an NSError object for receiving errors, otherwise nil.

Availability

Available in iOS 6.0 and later.

Declared In

CIFilter.h

filterNamesInCategories:

Returns an array of all published filter names that match all the specified categories.

+ (NSArray *)filterNamesInCategories:(NSArray *)categories

Parameters

categories: One or more of the filter category keys defined in “Filter Category Keys.” Pass nil to get all filters in all categories.

Return Value

An array that contains all published filter names that match all the categories specified by the categories argument.

Discussion

When you pass more than one filter category, this method returns the intersection of the filters in the categories. For example, if you pass the categories kCICategoryBuiltIn and kCICategoryColorAdjustment, you obtain all the filters that are members of both the built-in and color adjustment categories. But if you pass in kCICategoryGenerator and kCICategoryStylize, you will not get any filters returned to you because there are no filters that are members of both the generator and stylize categories. If you want to obtain all stylize and generator filters, you must call the filterNamesInCategories: method for each category separately and then merge the results.

Availability

Available in iOS 5.0 and later.

Declared In

CIFilter.h

filterNamesInCategory:

Returns an array of all published filter names in the specified category.

+ (NSArray *)filterNamesInCategory:(NSString *)category

Parameters

category: A string object that specifies one of the filter categories defined in “Filter Category Keys.”

Return Value

An array that contains all published names of the filter in a category.

Availability

Available in iOS 5.0 and later.

Declared In

CIFilter.h

filterWithName:

Creates a CIFilter object for a specific kind of filter.

+ (CIFilter *)filterWithName:(NSString *)name

Parameters

name: The name of the filter. You must make sure the name is spelled correctly, otherwise your app will run but not produce any output images. For that reason, you should check for the existence of the filter after calling this method.

Return Value

A CIFilter object whose input values are undefined.

Discussion

You should call setDefaults after you call this method or set values individually by calling setValue:forKey.

Availability

Available in iOS 5.0 and later.

Related Sample Code

PocketCoreImage

Declared In

CIFilter.h

filterWithName:keysAndValues:

Creates a CIFilter object for a specific kind of filter and initializes the input values.

+ (CIFilter *)filterWithName:(NSString *)name keysAndValues:key0, ...

Parameters

name: The name of the filter. You must make sure the name is spelled correctly, otherwise your app will run but not produce any output images. For that reason, you should check for the existence of the filter after calling this method.
key0,: A list of key-value pairs to set as input values to the filter. Each key is a constant that specifies the name of the input value to set, and must be followed by a value. You signal the end of the list by passing a nil value.

Return Value

A CIFilter object whose input values are initialized.

Availability

Available in iOS 5.0 and later.

Declared In

CIFilter.h

serializedXMPFromFilters:inputImageExtent:

Serializes filter parameters into XMP form that is suitable for embedding in an image.

+ (NSData*)serializedXMPFromFilters:(NSArray *)filters inputImageExtent:(CGRect)extent

Parameters

filters: The array of filters to serialize. See Discussion for the filters that can be serialized.
extent: The extent of the input image to the filter.

Discussion

At this time the only filters classes that can be serialized using this method are, CIAffineTransform, CICrop, and the filters returned by the CIImage methods autoAdjustmentFilters and autoAdjustmentFiltersWithOptions:. The parameters of other filter classes will not be serialized.

Availability

Available in iOS 6.0 and later.

Declared In

CIFilter.h

Instance Methods

attributes

Returns a dictionary of key-value pairs that describe the filter.

- (NSDictionary *)attributes

Return Value

A dictionary that contains a key for each input and output parameter for the filter. Each key is a dictionary that contains all the attributes of an input or output parameter.

Discussion

For example, the attributes dictionary for the CIColorControls filter contains the following information:

CIColorControls:

    CIAttributeFilterCategories = (

        CICategoryColorAdjustment,

        CICategoryVideo,

        CICategoryStillImage,

        CICategoryInterlaced,

        CICategoryNonSquarePixels,

        CICategoryBuiltIn

);

    CIAttributeFilterDisplayName = "Color Controls";

    CIAttributeFilterName = CIColorControls;

    inputBrightness = {

        CIAttributeClass = NSNumber;

        CIAttributeDefault = 0;

        CIAttributeIdentity = 0;

        CIAttributeMin = -1;

        CIAttributeSliderMax = 1;

        CIAttributeSliderMin = -1;

        CIAttributeType = CIAttributeTypeScalar;

};

    inputContrast = {

        CIAttributeClass = NSNumber;

        CIAttributeDefault = 1;

        CIAttributeIdentity = 1;

        CIAttributeMin = 0.25;

        CIAttributeSliderMax = 4;

        CIAttributeSliderMin = 0.25;

        CIAttributeType = CIAttributeTypeScalar;

};

    inputImage = {CIAttributeClass = CIImage; };

    inputSaturation = {

        CIAttributeClass = NSNumber;

        CIAttributeDefault = 1;

        CIAttributeIdentity = 1;

        CIAttributeMin = 0;

        CIAttributeSliderMax = 3;

        CIAttributeSliderMin = 0;

        CIAttributeType = CIAttributeTypeScalar;

};

    outputImage = {CIAttributeClass = CIImage; };

Availability

Available in iOS 5.0 and later.

Related Sample Code

PocketCoreImage

Declared In

CIFilter.h

inputKeys

Returns an array that contains the names of the input parameters to the filter.

- (NSArray *)inputKeys

Return Value

An array that contains the names of all input parameters to the filter.

Availability

Available in iOS 5.0 and later.

Declared In

CIFilter.h

name

The name of the filter.

- (NSString *)name

Return Value

A string that holds the name of the filter.

Availability

Available in iOS 5.0 and later.

Declared In

CIFilter.h

outputKeys

Returns an array that contains the names of the output parameters for the filter.

- (NSArray *)outputKeys

Return Value

An array that contains the names of all output parameters from the filter.

Availability

Available in iOS 5.0 and later.

Declared In

CIFilter.h

setDefaults

Sets all input values for a filter to default values.

- (void)setDefaults

Discussion

Input values whose default values are not defined are left unchanged.

Availability

Available in iOS 5.0 and later.

Related Sample Code

PocketCoreImage

Declared In

CIFilter.h

Constants

Filter Attribute Keys

Attributes for a filter and its parameters.

extern NSString *kCIAttributeFilterName;
extern NSString *kCIAttributeFilterDisplayName;
extern NSString *kCIAttributeFilterCategories;
extern NSString *kCIAttributeClass;
extern NSString *kCIAttributeType;
extern NSString *kCIAttributeMin;
extern NSString *kCIAttributeMax;
extern NSString *kCIAttributeSliderMin;
extern NSString *kCIAttributeSliderMax;
extern NSString *kCIAttributeDefault;
extern NSString *kCIAttributeIdentity;
extern NSString *kCIAttributeName;
extern NSString *kCIAttributeDisplayName;

Constants

kCIAttributeFilterName

The filter name, specified as an NSString object.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeFilterDisplayName

The localized version of the filter name that is displayed in the user interface.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeFilterCategories

An array of filter category keys that specifies all the categories in which the filter is a member.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeClass

The class name of the filter.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeType

One of the attribute types described in “Data Type Attributes.”

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeMin

The minimum value for a filter parameter, specified as a floating-point value.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeMax

The maximum value for a filter parameter, specified as a floating-point value.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeSliderMin

The minimum value, specified as a floating-point value, to use for a slider that controls input values for a filter parameter.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeSliderMax

The maximum value, specified as a floating-point value, to use for a slider that controls input values for a filter parameter.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeDefault

The default value, specified as a floating-point value, for a filter parameter.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeIdentity

If supplied as a value for a parameter, the parameter has no effect on the input image.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeName

The name of the attribute.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeDisplayName

The localized display name of the attribute.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

Discussion

Attribute keys are used for the attribute dictionary of a filter. Most entries in the attribute dictionary are optional. The attribute CIAttributeFilterName is mandatory. For a parameter, the attribute kCIAttributeClass is mandatory because it specifies the class name of the filter.

A parameter of type NSNumber does not necessarily need the attributes kCIAttributeMin and kCIAttributeMax. These attributes are not present when the parameter has no upper or lower bounds. For example, the Gaussian blur filter has a radius parameter with a minimum of 0 but no maximum value to indicate that all nonnegative values are valid.

Declared In

CIFilter.h

Data Type Attributes

Numeric data types.

extern NSString *kCIAttributeTypeTime;
extern NSString *kCIAttributeTypeScalar;
extern NSString *kCIAttributeTypeDistance;
extern NSString *kCIAttributeTypeAngle;
extern NSString *kCIAttributeTypeBoolean;
extern NSString *kCIAttributeTypeInteger;
extern NSString *kCIAttributeTypeCount;

Constants

kCIAttributeTypeTime

A parametric time for transitions, specified as a floating-point value in the range of 0.0 to 1.0.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeTypeScalar

A scalar value.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeTypeDistance

A distance.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeTypeAngle

An angle.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeTypeBoolean

A Boolean value.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeTypeInteger

An integer value.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeTypeCount

A positive integer value.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

Declared In

CIFilter.h

Vector Quantity Attributes

Vector data types.

extern NSString *kCIAttributeTypePosition;
extern NSString *kCIAttributeTypeOffset;
extern NSString *kCIAttributeTypePosition3;
extern NSString *kCIAttributeTypeRectangle

Constants

kCIAttributeTypePosition

A two-dimensional location in the working coordinate space. (A 2-element vector type.)

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeTypeOffset

An offset. (A 2-element vector type.)

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeTypePosition3

A three-dimensional location in the working coordinate space. (A 3-element vector type.)

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeTypeRectangle

A Core Image vector that specifies the x and y values of the rectangle origin, and the width (w) and height (h) of the rectangle. The vector takes the form [x, y, w, h]. (A 4-element vector type.)

Available in iOS 5.0 and later.

Declared in CIFilter.h.

Declared In

CIFilter.h

Color Attribute Keys

Color types.

extern NSString *kCIAttributeTypeColor;

Constants

kCIAttributeTypeColor

A Core Image color (CIColor object) that specifies red, green, and blue component values.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

Declared In

CIFilter.h

Image Attribute Keys

Image Types

extern NSString *kCIAttributeTypeImage;
extern NSString *kCIAttributeTypeTransform;

Constants

kCIAttributeTypeImage

A CIImage object.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIAttributeTypeTransform

An CGAffineTransform is associated with attribute.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

Filter Category Keys

Categories of filters.

extern NSString *kCICategoryDistortionEffect;
extern NSString *kCICategoryGeometryAdjustment;
extern NSString *kCICategoryCompositeOperation;
extern NSString *kCICategoryHalftoneEffect;
extern NSString *kCICategoryColorAdjustment;
extern NSString *kCICategoryColorEffect;
extern NSString *kCICategoryTransition;
extern NSString *kCICategoryTileEffect;
extern NSString *kCICategoryGenerator;
extern NSString *kCICategoryReduction;
extern NSString *kCICategoryGradient;
extern NSString *kCICategoryStylize;
extern NSString *kCICategorySharpen;
extern NSString *kCICategoryBlur;
extern NSString *kCICategoryVideo;
extern NSString *kCICategoryStillImage;
extern NSString *kCICategoryInterlaced;
extern NSString *kCICategoryNonSquarePixels;
extern NSString *kCICategoryHighDynamicRange ;
extern NSString *kCICategoryBuiltIn;

Constants

kCICategoryDistortionEffect

A filter that reshapes an image by altering its geometry to create a 3D effect. Using distortion filters, you can displace portions of an image, apply lens effects, make a bulge in an image, and perform other operation to achieve an artistic effect.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCICategoryGeometryAdjustment

A filter that changes the geometry of an image. Some of these filters are used to warp an image to achieve an artistic effects, but these filters can also be used to correct problems in the source image. For example, you can apply an affine transform to straighten an image that is rotated with respect to the horizon.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCICategoryCompositeOperation

A filter operates on two image sources, using the color values of one image to operate on the other. Composite filters perform computations such as computing maximum values, minimum values, and multiplying values between input images. You can use compositing filters to add effects to an image, crop an image, and achieve a variety of other effects.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCICategoryHalftoneEffect

A filter that simulates a variety of halftone screens, to mimic the halftone process used in print media. The output of these filters has the familiar “newspaper” look of the various dot patterns. Filters are typically named after the pattern created by the virtual halftone screen, such as circular screen or hatched screen.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCICategoryColorAdjustment

A filter that changes color values. Color adjustment filters are used to eliminate color casts, adjust hue, and correct brightness and contrast. Color adjustment filters do not perform color management; ColorSync performs color management. You can use Quartz 2D to specify the color space associated with an image. For more information, see Color Management Overview and Quartz 2D Programming Guide.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCICategoryColorEffect

A filter that modifies the color of an image to achieve an artistic effect. Examples of color effect filters include filters that change a color image to a sepia image or a monochrome image or that produces such effects as posterizing.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCICategoryTransition

A filter that provides a bridge between two or more images by applying a motion effect that defines how the pixels of a source image yield to that of the destination image.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCICategoryTileEffect

A filter that typically applies an effect to an image and then create smaller versions of the image (tiles), which are then laid out to create a pattern that’s infinite in extent.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCICategoryGenerator

A filter that generates a pattern, such as a solid color, a checkerboard, or a star shine. The generated output is typically used as input to another filter.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCICategoryReduction

A filter that reduces image data. These filters are used to solve image analysis problems.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCICategoryGradient

A filter that generates a fill whose color varies smoothly. Exactly how color varies depends on the type of gradient—linear, radial, or Gaussian.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCICategoryStylize

A filter that makes a photographic image look as if it was painted or sketched. These filters are typically used alone or in combination with other filters to achieve artistic effects.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCICategorySharpen

A filter that sharpens images, increasing the contrast between the edges in an image. Examples of sharpen filters are unsharp mask and sharpen luminance.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCICategoryBlur

A filter that softens images, decreasing the contrast between the edges in an image. Examples of blur filters are Gaussian blur and zoom blur.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCICategoryVideo

A filter that works on video images.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCICategoryStillImage

A filter that works on still images.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCICategoryInterlaced

A filter that works on interlaced images.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCICategoryNonSquarePixels

A filter that works on non-square pixels.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCICategoryHighDynamicRange

A filter that works on high dynamic range pixels.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCICategoryBuiltIn

A filter provided by Core Image. This distinguishes built-in filters from plug-in filters.

Available in iOS 5.0 and later.

Declared in CIFilter.h.

Declared In

CIFilter.h

Filter Parameter Keys

Keys for input parameters to filters.

extern NSString *kCIOutputImageKey;
extern NSString *kCIInputBackgroundImageKey;
extern NSString *kCIInputImageKey;
extern NSString *kCIInputVersionKey;

Constants

kCIOutputImageKey

A key for the CIImage object produced by a filter.

Available in OS X v10.5 and later. Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIInputBackgroundImageKey

A key for the CIImage object to use as a background image.

Available in OS X v10.5 and later. Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIInputImageKey

A key for the CIImage object to use as an input image. For filters that also use a background image, this key refers to the foreground image.

Available in OS X v10.5 and later. Available in iOS 5.0 and later.

Declared in CIFilter.h.

kCIInputVersionKey

A key that specifies a version number.

Not available in OS X. Available in iOS 6.0 and later.

Declared in CIFilter.h.

Discussion

These keys represent some of the most commonly used input parameters. A filter can use other kinds of input parameters.

Declared In

CIFIlter.h

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

CIFilter Class Reference

Overview

Subclassing Notes

Tasks

Creating a Filter

Accessing Registered Filters

Getting Filter Parameters and Attributes

Setting Default Values

Serializing and Deserializing Filters

Properties

outputImage

Availability

Declared In

Class Methods

filterArrayFromSerializedXMP:inputImageExtent:error:

Parameters

Availability

Declared In

filterNamesInCategories:

Parameters

Return Value

Discussion

Availability

See Also

Declared In

filterNamesInCategory:

Parameters

Return Value

Availability

See Also

Declared In

filterWithName:

Parameters

Return Value

Discussion

Availability

See Also

Related Sample Code

Declared In

filterWithName:keysAndValues:

Parameters

Return Value

Availability

See Also

Declared In

serializedXMPFromFilters:inputImageExtent:

Parameters

Discussion

Availability

Declared In

Instance Methods

attributes

Return Value

Discussion

Availability

Related Sample Code

Declared In

inputKeys

Return Value

Availability

Declared In

name

Return Value

Availability

Declared In

outputKeys

Return Value

Availability

Declared In

setDefaults

Discussion

Availability

Related Sample Code

Declared In

Constants

Filter Attribute Keys

Constants

Discussion

Declared In

Data Type Attributes