Mac Developer Library

Developer

QuartzCore Framework Reference CIFilterGenerator Class Reference

Options
Deployment Target:

On This Page
Language:

CIFilterGenerator

Inheritance


Conforms To


Import Statement


Swift

import QuartzCore

Objective-C

@import QuartzCore;

Availability


OS X v10.5 and later

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 ImageKit Additions).

  • Creates and returns an empty filter generator object.

    Declaration

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import QuartzCore;

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import QuartzCore;

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    init!(contentsOfURL aURL: NSURL!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.5 and later.

  • Adds an object to the filter chain.

    Declaration

    Swift

    func connectObject(_ sourceObject: AnyObject!, withKey sourceKey: String!, toObject targetObject: AnyObject!, withKey targetKey: String!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.5 and later.

  • Removes the connection between two objects in the filter chain.

    Declaration

    Swift

    func disconnectObject(_ sourceObject: AnyObject!, withKey sourceKey: String!, toObject targetObject: AnyObject!, withKey targetKey: String!)

    Objective-C

    - (void)disconnectObject:(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. 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.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.5 and later.

  • Returns an array of the exported keys.

    Declaration

    Swift

    func exportedKeys() -> [NSObject : AnyObject]!

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func exportKey(_ key: String!, fromObject targetObject: AnyObject!, withName exportedKeyName: String!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.5 and later.

  • Removes a key that was previously exported.

    Declaration

    Swift

    func removeExportedKey(_ exportedKeyName: String!)

    Objective-C

    - (void)removeExportedKey:(NSString *)exportedKeyName

    Parameters

    exportedKeyName

    The name of the key you want to remove.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.5 and later.

  • Sets a dictionary of attributes for an exported key.

    Declaration

    Swift

    func setAttributes(_ attributes: [NSObject : AnyObject]!, forExportedKey key: String!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.5 and later.

  • Archives a filter generator object to a filter generator file.

    Declaration

    Swift

    func writeToURL(_ aURL: NSURL!, atomically flag: Bool) -> Bool

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.5 and later.

  • Registers the name associated with a filter chain.

    Declaration

    Swift

    func registerFilterName(_ name: String!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.5 and later.

  • Creates a filter object based on the filter chain.

    Declaration

    Swift

    func filter() -> CIFilter!

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.5 and later.

  • Keys for the exported parameters of a filter generator object.

    Declaration

    Swift

    let kCIFilterGeneratorExportedKeyName: String let kCIFilterGeneratorExportedKey: String let kCIFilterGeneratorExportedKeyTargetObject: String

    Objective-C

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

    Constants

    • kCIFilterGeneratorExportedKeyName

      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.

    • kCIFilterGeneratorExportedKey

      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.

    • kCIFilterGeneratorExportedKeyTargetObject

      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.