Class

CIFilter

An image processor that produces an image by manipulating one or more input images or by generating new image data.

Declaration

@interface CIFilter : NSObject

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 mutable, and thus cannot be shared safely among threads. Each thread must create its own CIFilter objects, but you can pass a filter’s immutable input and output CIImage objects between threads.

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 custom filter effects:

  • By chaining together two or more built-in Core Image filters

  • By using an image-processing kernel that you write

See Core Image Programming Guide for details.

Methods to Override

Regardless of whether your subclass provides its effect by chaining filters or implementing its own kernel, you should:

  • Declare any input parameters as properties whose names are prefixed with input, such as inputImage.

  • Override the setDefaults methods to provide default values for any input parameters you’ve declared.

  • Implement an outputImage method to create a new CIImage with your filter’s effect.

Special Considerations

The CIFilter class automatically manages input parameters when archiving, copying, and deallocating filters. For this reason, your subclass must obey the following guidelines to ensure proper behavior:

  • Store input parameters in instance variables whose names are prefixed with input.

    Don’t use auto-synthesized instance variables, because their names are automatically prefixed with an underscore. Instead, synthesize the property manually. For example:

    @synthesize inputMyParameter;

  • If using manual reference counting, don’t release input parameter instance variables in your dealloc method implementation. The dealloc implementation in the CIFilter class uses Key-value coding to automatically set the values of all input parameters to nil.

Topics

Creating a Filter

+ filterWithName:

Creates a CIFilter object for a specific kind of filter.

+ filterWithName:withInputParameters:

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

+ filterWithName:keysAndValues:

Creates a CIFilter object for a specific kind of filter and initializes the input values with a nil-terminated list of arguments.

Creating a Filter from a RAW Image

+ filterWithImageData:options:

A filter which allows the processing of RAW images

+ filterWithImageURL:options:

A filter which allows the processing of RAW images

+ filterWithCVPixelBuffer:properties:options:

Creates a filter from a Core Video pixel buffer.

Accessing Registered Filters

+ filterNamesInCategories:

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

+ filterNamesInCategory:

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

Registering a Filter

+ registerFilterName:constructor:classAttributes:

Publishes a custom filter that is not packaged as an image unit.

Getting Filter Parameters and Attributes

- setName:

A name associated with a filter.

enabled

A Boolean value that determines whether the filter is enabled. Animatable.

attributes

A dictionary of key-value pairs that describe the filter.

inputKeys

The names of all input parameters to the filter.

outputKeys

The names of all output parameters from the filter.

outputImage

Returns a CIImage object that encapsulates the operations configured in the filter.

Setting Default Values

- setDefaults

Sets all input values for a filter to default values.

Applying a Filter

- apply:arguments:options:

Produces a CIImage object by applying arguments to a kernel function and using options to control how the kernel function is evaluated.

- apply:

Produces a CIImage object by applying a kernel function.

Getting Localized Information for Registered Filters

+ localizedNameForFilterName:

Returns the localized name for the specified filter name.

+ localizedNameForCategory:

Returns the localized name for the specified filter category.

+ localizedDescriptionForFilterName:

Returns the localized description of a filter for display in the user interface.

+ localizedReferenceDocumentationForFilterName:

Returns the location of the localized reference documentation that describes the filter.

Creating a Configuration View for a Filter

- viewForUIConfiguration:excludedKeys:

Returns a filter view for the filter.

Serializing and Deserializing Filters

+ serializedXMPFromFilters:inputImageExtent:

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

+ filterArrayFromSerializedXMP:inputImageExtent:error:

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

Constants

Filter Attribute Keys

Attributes for a filter and its parameters.

Options for Applying a Filter

Options that control the application of a custom Core Image filter.

User Interface Control Options

Sets of controls for various user scenarios.

User Interface Options

Keys or values for the size of the input parameter controls for a filter view.

Filter Parameter Keys

Keys for input parameters to filters.

RAW Image Options

Options for creating a CIFilter object from RAW image data.

Type Methods

Relationships

Inherits From

See Also

First Steps

Processing an Image Using Built-in Filters

Apply effects such as sepia tint, highlight strengthening, and scaling to images.

CIImage

A representation of an image to be processed or produced by Core Image filters.

CIContext

An evaluation context for rendering image processing results and performing image analysis.

Basic Data Types

Colors, vectors, and other types used in applying or creating image filters.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software