Core Image Programming Guide

Querying the System for Filters

Core Image provides methods that let you query the system for the available built-in filters and the associated information about each filter—display name, input parameters, parameter types, defaults values, and so on. Querying the system provides you with the most up-to-date information about available filters. If your app supports letting users choose and set filters, you can use this information when creating a user interface for a filter.

If you want to find all available filters for a list of categories, you can call the method filterNamesInCategories:, supplying an array of category constants from those listed in the tables. The method returns an NSArray object populated with the filter names for each category. You can obtain a list of all filters for all categories by supplying nil instead of an array of category constants.

A filter can be a member of more than one category. A category can specify:

The type of effect produced by the filter (color adjustment, distortion, and so forth). See Table 4-1.

The usage of the filter (still image, video, high dynamic range, and so forth). See Table 4-2.

Whether the filter is provided by Core Image (built-in). See Table 4-3.

You replace the string "<# Filter Name Here #>" with the name of the filter you are interested in. Attributes include such things as name, categories, class, minimum, and maximum. See CIFilter Class Reference for the complete list of attributes that can be returned.

Building a Dictionary of Filters

If your app provides a user interface, it can consult a filter dictionary to create and update the user interface. For example, filter attributes that are Boolean would require a checkbox or similar user interface element, and attributes that vary continuously over a range could use a slider. You can use the maximum and minimum values as the basis for text labels. The default attribute setting would dictate the initial setting in the user interface.

Filter names and attributes provide all the information you need to build a user interface that allows users to choose a filter and control its input parameters. The attributes for a filter tell you how many input parameters the filter has, the parameter names, the data type, and the minimum, maximum, and default values.

Note: If you are interested in building a user interface for a Core Image filter, see IKFilterUIView Class Reference, which provides a view that contains input parameter controls for a Core Image filter.

Listing 4-1 shows code that gets filter names and builds a dictionary of filters by functional categories. The code retrieves filters in these categories—kCICategoryGeometryAdjustment, kCICategoryDistortionEffect, kCICategorySharpen, and kCICategoryBlur—but builds the dictionary based on app-defined functional categories, such as Distortion and Focus. Functional categories are useful for organizing filter names in a menu that makes sense for the user. The code does not iterate through all possible Core Image filter categories, but you can easily extend this code by following the same process.

Listing 4-1 Code that builds a dictionary of filters by functional categories

Listing 4-2 shows the buildFilterDictionary routine called in Listing 4-1. This routine builds a dictionary of attributes for each of the filters in a functional category. A detailed explanation for each numbered line of code follows the listing.

Takes an array of filter names as an input parameter. Recall from Listing 4-1 that this array can be a concatenation of filter names from more than one Core Image filter category. In this example, the array is based upon functional categories set up by the app (Distortion or Focus).

Iterates through the array of filter names.

Retrieves the filter object for the filter name.

Retrieves the attributes dictionary for a filter and adds it to the dictionary returned by the routine.

Note: Apps that run in OS X v10.5 and later can use the CIFilter Image Kit additions to provide a filter browser and a view for setting filter input parameters. See CIFilter Image Kit Additions and Image Kit Programming Guide.