---

CIFilterGenerator Class Reference

Overview

The CIFilterGenerator class provides methods for creating a CIFilter object by chaining together existing CIFilter objects to create complex effects. (A filter chain refers to the CIFilter objects that are connected in the CIFilterGenerator object.) The complex effect can be encapsulated as a CIFilterGenerator object and saved as a file so that it can be used again. The filter generator file contains an archived instance of all the CIFilter objects that are chained together.

Any filter generator files that you copy to /Library/Graphics/Image Units/ are loaded when any of the loading methods provided by the CIPlugIn class are invoked. A CIFilterGenerator object is registered by its filename or, if present, by a class attribute that you supply in its description.

You can create a CIFilterGenerator object programmatically, using the methods provided by the CIFilterGenerator class, or by using the editor view provided by Core Image (see CIFilter Image Kit Additions).

Tasks

Creating Filter Generator Objects

• + filterGenerator
• + filterGeneratorWithContentsOfURL:

Initializing a Filter Generator Object

• – initWithContentsOfURL:

Connecting and Disconnecting Objects

• – connectObject:withKey:toObject:withKey:
• – disconnectObject:withKey:toObject:withKey:

Managing Exported Keys

• – exportedKeys
• – exportKey:fromObject:withName:
• – removeExportedKey:
• – setAttributes:forExportedKey:

Setting and Getting Class Attributes

• – classAttributes
• – setClassAttributes:

Archiving a Filter Generator Object

• – writeToURL:atomically:

Registering a Filter Chain

• – registerFilterName:

Creating a Filter from a Filter Chain

• – filter

Class Methods

filterGenerator

Creates and returns an empty filter generator object.

+ (CIFilterGenerator *)filterGenerator

Return Value

A CIFilterGenerator object.

Discussion

You use the returned object to connect two or more CIFilter objects and input images. It is also valid to have only one CIFilter object in a filter generator.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• + filterGeneratorWithContentsOfURL:

Declared In

CIFilterGenerator.h

filterGeneratorWithContentsOfURL:

Creates and returns a filter generator object and initializes it with the contents of a filter generator file.

+ (CIFilterGenerator *)filterGeneratorWithContentsOfURL:(NSURL *)aURL

Parameters

aURL

The location of a filter generator file.

Return Value

A CIFilterGenerator object; returns nil if the file can’t be read.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• + filterGenerator

Declared In

CIFilterGenerator.h

Instance Methods

classAttributes

Retrieves the class attributes associated with a filter.

- (NSDictionary *)classAttributes

Return Value

An NSDictionary object that contains the class attributes for a filter, or nil if attributes are not set for the filter.

Discussion

For more information about class attributes for a filter, see Core Image Programming Guide and the filter attributes key constants defined in CIFilter Class Reference.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setClassAttributes:

Declared In

CIFilterGenerator.h

connectObject:withKey:toObject:withKey:

Adds an object to the filter chain.

- (void)connectObject:(id)sourceObject withKey:(NSString *)sourceKey toObject:(id)targetObject withKey:(NSString *)targetKey

Parameters

sourceObject

A CIFilter object, a CIImage object, or a the path (an NSString or NSURL object) to an image.

sourceKey

The key that specifies the source object. For example, if the source is the output image of a filter, pass the outputImage key. Pass nil if the source object is used directly.

targetObject

The object that to link the source object to.

targetKey

The key that specifies the target for the source. For example, if you are connecting the source to the input image of a CIFilter object, you would pass the inputImage key.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – disconnectObject:withKey:toObject:withKey:

Declared In

CIFilterGenerator.h

disconnectObject:withKey:toObject:withKey:

Removes the connection between two objects in the filter chain.

- (void)disconnectObject:(id)sourceObject withKey:(NSString *)key toObject:(id)targetObject withKey:(NSString *)targetKey

Parameters

sourceObject

A CIFilter object, a CIImage object, or a the path (an NSString or NSURL object) to an image.

sourceKey

The key that specifies the source object. Pass nil if the source object is used directly.

targetObject

The object that you want to disconnect the source object from.

targetKey

The key that specifies the target that the source object is currently connected to.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – connectObject:withKey:toObject:withKey:

Declared In

CIFilterGenerator.h

exportedKeys

Returns an array of the exported keys.

- (NSDictionary *)exportedKeys

Return Value

An array of dictionaries that describe the exported key and target object. See kCIFilterGeneratorExportedKey, kCIFilterGeneratorExportedKeyTargetObject, and kCIFilterGeneratorExportedKey for keys used in the dictionary.

Discussion

This method returns the keys that you exported using the exportKey:fromObject:withName: method or that were exported before being written to the file from which you read the filter chain.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – exportKey:fromObject:withName:

Declared In

CIFilterGenerator.h

exportKey:fromObject:withName:

Exports an input or output key of an object in the filter chain.

- (void)exportKey:(NSString *)key fromObject:(id)targetObject withName:(NSString *)exportedKeyName

Parameters

key

The key to export from the target object (for example, inputImage).

targetObject

The object associated with the key (for example, the filter).

exportedKeyName

A unique name to use for the exported key. Pass nil to use the original key name.

Discussion

When you create a CIFilter object from a CIFilterGenerator object, you might want the filter client to be able to set some of the parameters associated with the filter chain. You can make a parameter settable by exporting the key associated with the parameter. If the exported key represents an input parameter of the filter, the key is exported as an input key. If the key represents an output parameter, it is exported as an output key.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – exportedKeys
• – setAttributes:forExportedKey:
• – removeExportedKey:

Declared In

CIFilterGenerator.h

filter

Creates a filter object based on the filter chain.

- (CIFilter *)filter

Return Value

A CIFilter object.

Discussion

The topology of the filter chain is immutable, meaning that any changes you make to the filter chain are not reflected in the filter. The returned filer has the input an output keys that are exported.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CIFilterGenerator.h

initWithContentsOfURL:

Initializes a filter generator object with the contents of a filter generator file.

- (id)initWithContentsOfURL:(NSURL *)aURL

Parameters

aURL

The location of a filter generator file.

Return Value

The initialized CIFilterGenerator object. Returns nil if the file can’t be read.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• + filterGenerator
• + filterGeneratorWithContentsOfURL:

Declared In

CIFilterGenerator.h

registerFilterName:

Registers the name associated with a filter chain.

- (void)registerFilterName:(NSString *)name

Parameters

name

A unique name for the filter chain you want to register.

Discussion

This method allows you to register the filter chain as a named filter in the Core Image filter repository. You can then create a CIFilter object from it using the the filterWithName: method of the CIFilter class.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CIFilterGenerator.h

removeExportedKey:

Removes a key that was previously exported.

- (void)removeExportedKey:(NSString *)exportedKeyName

Parameters

exportedKeyName

The name of the key you want to remove.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – exportKey:fromObject:withName:

Declared In

CIFilterGenerator.h

setAttributes:forExportedKey:

Sets a dictionary of attributes for an exported key.

- (void)setAttributes:(NSDictionary *)attributes forExportedKey:(NSString *)key

Parameters

attributes

A dictionary that describes the attributes associated with the specified key.

key

The exported key whose attributes you want to set.

Discussion

By default, the exported key inherits the attributes from its original key and target object. You can use this method to change one or more of the existing attributes for the key, such as the default value or maximum value. For more information on attributes, see CIFilter Class Reference and Core Image Programming Guide.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – exportedKeys
• – exportKey:fromObject:withName:

Declared In

CIFilterGenerator.h

setClassAttributes:

Seta the class attributes for a filter.

- (void)setClassAttributes:(NSDictionary *)attributes

Parameters

attributes

An NSDictionary object that contains the class attributes for a filter For information on the required attributes, see CIFilter Class Reference and Core Image Programming Guide.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – classAttributes

Declared In

CIFilterGenerator.h

writeToURL:atomically:

Archives a filter generator object to a filter generator file.

- (BOOL)writeToURL:(NSURL *)aURL atomically:(BOOL)flag

Parameters

aURL

A location for the file generator file.

flag

Pass true to specify that Core Image should create an interim file to avoid overwriting an existing file.

Return Value

Returns true if the the object is successfully archived to the file.

Discussion

Use this method to save your filter chain to a file for later use.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CIFilterGenerator.h

Constants

Exported Keys

Keys for the exported parameters of a filter generator object.

extern NSString *const kCIFilterGeneratorExportedKey;
extern NSString *const kCIFilterGeneratorExportedKeyTargetObject;
extern NSString *const kCIFilterGeneratorExportedKeyName;

Constants

kCIFilterGeneratorExportedKeyName

The key (CIFilterGeneratorExportedKeyName) for the name used to export the CIFilterGenerator object. The associated value is a string that specifies a unique name for the filter generator object.

Available in Mac OS X v10.5 and later.

kCIFilterGeneratorExportedKey

The key (CIFilterGeneratorExportedKey) for the exported parameter. The associated value is the key name of the parameter you are exporting, such as inputRadius.

kCIFilterGeneratorExportedKeyTargetObject

The target object (CIFilterGeneratorExportedKeyTargetObject) for the exported key. The associated value is the name of the object, such as CIMotionBlur.

Declared In

CIFilterGenerator.h

---