CIFilterGenerator Class Reference

Inherits from
NSObject
Conforms to
NSCoding
NSCopying
CIFilterConstructor
NSObject (NSObject)
Framework
Library/Frameworks/QuartzCore.framework
Availability
OS X v10.5 and later
Declared in
CIFilterGenerator.h
Companion guides
Core Image Programming Guide
Core Image Filter Reference
Related sample code

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

Initializing a Filter Generator Object

Connecting and Disconnecting Objects

Managing Exported Keys

Setting and Getting Class Attributes

Archiving a Filter Generator Object

Registering a Filter Chain

Creating a Filter from a Filter Chain

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 OS X v10.5 and later.
See Also
Related Sample Code
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 OS X v10.5 and later.
See Also
Related Sample Code
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 OS X v10.5 and later.
See Also
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 OS X v10.5 and later.
See Also
Related Sample Code
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 OS X v10.5 and later.
See Also
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 OS X v10.5 and later.
See Also
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 OS X v10.5 and later.
See Also
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 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 OS X v10.5 and later.
See Also
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 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 OS X v10.5 and later.
See Also
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 OS X v10.5 and later.
See Also
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 OS X v10.5 and later.
See Also
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 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 OS X v10.5 and later.

Declared in CIFilterGenerator.h.

kCIFilterGeneratorExportedKey

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

Available in OS X v10.5 and later.

Declared in CIFilterGenerator.h.

kCIFilterGeneratorExportedKeyTargetObject

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

Available in OS X v10.5 and later.

Declared in CIFilterGenerator.h.

Declared In
CIFilterGenerator.h


© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-12-05)

Did this document help you? Yes It's good, but... Not helpful...