Class

CIFilter

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

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.

Symbols

Creating a Filter

init?(name: String)

Creates a CIFilter object for a specific kind of filter.

init?(name: String, withInputParameters: [String : Any]?)

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

Creating a Filter from a RAW Image

init!(imageData: Data!, options: [AnyHashable : Any]! = [:])

A filter which allows the processing of RAW images

init!(imageURL: URL!, options: [AnyHashable : Any]! = [:])

A filter which allows the processing of RAW images

Accessing Registered Filters

class func filterNames(inCategories: [String]?)

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

class func filterNames(inCategory: String?)

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

Registering a Filter

Getting Filter Parameters and Attributes

var name: String

A name associated with a filter.

var attributes: [String : Any]

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

var inputKeys: [String]

The names of all input parameters to the filter.

var outputKeys: [String]

The names of all output parameters from the filter.

var outputImage: CIImage?

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

Setting Default Values

func setDefaults()

Sets all input values for a filter to default values.

Applying a Filter

func apply(CIKernel, arguments: [Any]?, options: [String : Any]? = nil)

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

Getting Localized Information for Registered Filters

class func localizedName(forFilterName: String)

Returns the localized name for the specified filter name.

class func localizedName(forCategory: String)

Returns the localized name for the specified filter category.

class func localizedDescription(forFilterName: String)

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

class func localizedReferenceDocumentation(forFilterName: String)

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

Using Filters with Core Animation

var isEnabled: Bool

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

Creating a Configuration View for a Filter

Serializing and Deserializing Filters

class func serializedXMP(from: [CIFilter], inputImageExtent: CGRect)

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

Constants

Filter Attribute Keys

Attributes for a filter and its parameters.

Data Type Attributes

Numeric data types.

Vector Quantity Attributes

Vector data types.

Filter Category Keys

Categories of filters.

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.

Relationships

Inherits From