Mac Developer Library

Developer

Quartz Framework Reference QCPlugIn Class Reference

Options
Deployment Target:

On This Page
Language:

QCPlugIn

The QCPlugIn class provides the base class to subclass for writing custom Quartz Composer patches. You implement a custom patch by subclassing QCPlugIn, overriding the appropriate methods, packaging the code as an NSBundle object, and installing the bundle in the appropriate location. A bundle can contain more than one subclass of QCPlugIn, allowing you to provide a suite of custom patches in one bundle. Quartz Composer Custom Patch Programming Guide provides detailed instructions on how to create and package a custom patch. QCPlugIn Class Reference supplements the information in the programming guide.

The methods related to the executing the custom patch (called when the Quartz Composer engine is rendering) are passed an opaque object that conforms to the QCPlugInContext Protocol protocol. This object represents the execution context of the QCPlugIn object. You should not retain the execution context or use it outside of the scope of the execution method that it is passed to.

Inheritance


Conforms To


Import Statement


Swift

import Quartz

Objective-C

@import Quartz;

Availability


Available in OS X v10.5 and later.
  • Returns the execution mode of the custom patch.

    Declaration

    Swift

    class func executionMode() -> QCPlugInExecutionMode

    Objective-C

    + (QCPlugInExecutionMode)executionMode

    Return Value

    The execution mode of the custom patch. See “Execution Modes” for the constants you can return.

    Discussion

    You must implement this method to define whether your custom patch is a provider, a processor, or a consumer.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Returns the time mode for the custom patch.

    Declaration

    Swift

    class func timeMode() -> QCPlugInTimeMode

    Objective-C

    + (QCPlugInTimeMode)timeMode

    Return Value

    The time mode of the custom patch. See “Time Modes” for the constants you can return.

    Discussion

    You must implement this method to define whether you custom patch depends on time, doesn’t depend on time, or needs time to idle.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Performs the processing or rendering tasks appropriate for the custom patch.

    Declaration

    Swift

    func execute(_ context: QCPlugInContext!, atTime time: NSTimeInterval, withArguments arguments: [NSObject : AnyObject]!) -> Bool

    Objective-C

    - (BOOL)execute:(id<QCPlugInContext>)context atTime:(NSTimeInterval)time withArguments:(NSDictionary *)arguments

    Parameters

    context

    An opaque object , conforming to the QCPlugInContext Protocol protocol, that represents the execution context of the QCPlugIn object. Do not retain this object or use it outside of the scope of this method.

    time

    The execution interval.

    arguments

    A dictionary of arguments that can be used during execution. See “Execution Arguments”.

    Return Value

    NOfalse indicates the custom patch was not able to execute successfully. In this case, the Quartz Composer engine stops rendering the current frame.

    Discussion

    The Quartz Composer engine calls this method each time your custom patch needs to execute. You must implement this method. The method should perform whatever tasks are appropriate for the custom patch, such as:

    • reading values from the input ports

    • computing output values

    • updating the values on the output ports

    • rendering to the execution context

    For example implementations of this method, see Quartz Composer Custom Patch Programming Guide.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Allows you to perform custom setup tasks before the Quartz Composer engine starts rendering.

    Declaration

    Swift

    func startExecution(_ context: QCPlugInContext!) -> Bool

    Objective-C

    - (BOOL)startExecution:(id<QCPlugInContext>)context

    Parameters

    context

    An opaque object , conforming to the QCPlugInContext Protocol protocol, that represents the execution context of the QCPlugIn object. Do not retain this object or use it outside of the scope of this method.

    Return Value

    NOfalse indicates a fatal error occurred and prevents the Quartz Composer engine from starting.

    Discussion

    The Quartz Composer engine calls this method when your custom patch starts to render. You can optionally override this execution method to perform setup tasks.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Allows you to perform custom tasks when the execution of the QCPlugIn object is resumed.

    Declaration

    Swift

    func enableExecution(_ context: QCPlugInContext!)

    Objective-C

    - (void)enableExecution:(id<QCPlugInContext>)context

    Parameters

    context

    An opaque object , conforming to the QCPlugInContext Protocol protocol, that represents the execution context of the QCPlugIn object. Do not retain this object or use it outside of the scope of this method.

    Discussion

    The Quartz Composer engine calls this method when results start to be pulled from the custom patch. You can optionally override this execution method to perform custom tasks at that time.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Allows you to perform custom tasks when the execution of the QCPlugIn object is paused.

    Declaration

    Swift

    func disableExecution(_ context: QCPlugInContext!)

    Objective-C

    - (void)disableExecution:(id<QCPlugInContext>)context

    Parameters

    context

    An opaque object , conforming to the QCPlugInContext Protocol protocol, that represents the execution context of the QCPlugIn object. Do not retain this object or use it outside of the scope of this method.

    Discussion

    The Quartz Composer engine calls this method when results are no longer being pulled from the custom patch. You can optionally override this execution method to perform custom tasks at that time.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Allows you to perform custom tasks when the QCPlugIn object stops executing.

    Declaration

    Swift

    func stopExecution(_ context: QCPlugInContext!)

    Objective-C

    - (void)stopExecution:(id<QCPlugInContext>)context

    Parameters

    context

    An opaque object , conforming to the QCPlugInContext Protocol protocol, that represents the execution context of the QCPlugIn object. Do not retain this object or use it outside of the scope of this method.

    Discussion

    The Quartz Composer engine calls this method when it stops executing. You can optionally override this execution method to perform cleanup tasks.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Returns a dictionary that contains strings for the user interface that describe the custom patch.

    Declaration

    Swift

    class func attributes() -> [NSObject : AnyObject]!

    Objective-C

    + (NSDictionary *)attributes

    Return Value

    The dictionary can contain one or more of these keys along with the appropriate string: QCPlugInAttributeNameKey, QCPlugInAttributeDescriptionKey, and QQCPlugInAttributeCopyrightKey.

    Discussion

    It’s recommended that you implement this method to enhance the experience of those who use your custom patch. The attribute name string that you provide is displayed in the Quartz Composer editor window when the custom patch name is selected in the Patch Creator (see figure). The attribute description key is displayed in the Information pane of the inspector for the custom patch.

    image: ../Art/patch_info.pdf

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Returns a dictionary that contains strings for the user interface that describe the optional attributes for ports created from properties.

    Declaration

    Swift

    class func attributesForPropertyPortWithKey(_ key: String!) -> [NSObject : AnyObject]!

    Objective-C

    + (NSDictionary *)attributesForPropertyPortWithKey:(NSString *)key

    Parameters

    key

    The name of the property.

    Return Value

    A dictionary that contains key-value pairs for the port’s attributes. The keys must be one or more of the constants defined in Input and Output Port Attributes.

    Discussion

    It’s recommended that you implement this method to enhance the experience of those who use your custom patch. The attributes appear in a help tag when the user hovers a pointer over the property port on your custom patch. At a minimum, you should provide a user-readable name for the port. It might also be helpful to provide default, minimum, and maximum values for the port.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

    See Also

    + attributes

  • Creates and returns a view controller for the Settings pane of a custom patch.

    Declaration

    Swift

    func createViewController() -> QCPlugInViewController!

    Objective-C

    - (QCPlugInViewController *)createViewController

    Return Value

    A view controller for the custom patch. Quartz Composer releases the controller when it is no longer needed. If necessary, you can return a subclass of QCPlugInViewController, but this it not typically done.

    Discussion

    This extension to the QCPlugInViewController class provides user-interface support for the Settings pane of the inspector for a custom patch. You must override this method if your custom patch provides a Settings pane. The QCPlugInViewController object acts as a controller for Cocoa bindings between the custom patch instance (the model) and the NSView that contains the controls. It loads the nib file from the bundle.

    The implementation is straightforward. You allocate a QCPlugInViewController object, initialize it, and provide the name of the nib file that contains the user interface for the Settings pane.

    Note that this method follows the Core Foundation “create” rule. See the ownership policy in Memory Management Programming Guide for Core Foundation.

    For example, if the nib file name that contains the settings pane is MySettingsPane.nib, the implementation is:

    • - (QCPlugInViewController *) createViewController
    • {
    • return [[QCPlugInViewController alloc] initWithPlugIn:self
    • viewNibName:@"MySettingsPane"];
    • }

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

    See Also

    + plugInKeys

  • Returns the keys for the internal settings of a custom patch.

    Declaration

    Swift

    class func plugInKeys() -> [AnyObject]!

    Objective-C

    + (NSArray *)plugInKeys

    Return Value

    An array of keys used for key-value coding (KVC) of the internal settings.

    Discussion

    You must override this method if your patch provides a Settings pane. This keys are used for automatic serialization of the internal settings and are also used by the QCPlugInViewController instance for the Settings pane. The implementation is straightforward; the keys are strings that represent the instance variables used for the Settings pane. For example, the plugInKeys method for these instance variables:

    • @property(ivar, byref) NSColor * systemColor;
    • @property(ivar, byref) NSConfiguration * systemConfiguration;

    are:

    • + (NSArray*) plugInKeys
    • {
    • return [NSArray arrayWithObjects: @"systemColor",
    • @"systemConfiguration",
    • nil];
    • }

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Provides custom serialization for patch internal settings that do not comply to the NSCoding protocol.

    Declaration

    Swift

    func serializedValueForKey(_ key: String!) -> AnyObject!

    Objective-C

    - (id)serializedValueForKey:(NSString *)key

    Parameters

    key

    The key for the value to retrieve.

    Return Value

    Either nil or a value that’s compliant with property lists: NSString, NSNumber, NSDate, NSData, NSArray, or NSDictionary.

    Discussion

    If your patch has internal settings that do not conform to the NSCoding protocol, you must implement this method.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Provides custom deserialization for patch internal settings that were previously serialized using the method serializedValueForKey:.

    Declaration

    Swift

    func setSerializedValue(_ serializedValue: AnyObject!, forKey key: String!)

    Objective-C

    - (void)setSerializedValue:(id)serializedValue forKey:(NSString *)key

    Parameters

    serializedValue

    The value to deserialize.

    key

    The key for the value to deserialize.

    Discussion

    If your patch has internal settings that do not conform to the NSCoding protocol, you must implement this method. After you deserialize the value, you need to call [self set:value forKey:key] to set the corresponding internal setting of the custom patch instance to the deserialized value.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Loads a Quartz Composer plug-in bundle from the specified path.

    Declaration

    Swift

    class func loadPlugInAtPath(_ path: String!) -> Bool

    Objective-C

    + (BOOL)loadPlugInAtPath:(NSString *)path

    Parameters

    path

    The location of the bundle.

    Return Value

    YEStrue if successful.

    Discussion

    Call this method only if you need to load a plug-in bundle from a nonstandard location. Typically you don’t need to call this method because Quartz Composer automatically loads bundles that you install in one of the following locations:

    • /Library/Graphics/Quartz Composer Plug-Ins

    • ~/Library/Graphics/Quartz Composer Plug-Ins

    This method does nothing if the bundle is already loaded. (This method does not load in all environments. Web Kit, for example, cannot load custom patches.)

    The bundle can contain more than one QCPlugIn subclass. After the bundle is loaded, each QCPlugIn subclass appears as a patch in the Quartz Composer patch library.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Registers a QCPlugIn subclass.

    Declaration

    Swift

    class func registerPlugInClass(_ aClass: AnyClass!)

    Objective-C

    + (void)registerPlugInClass:(Class)aClass

    Parameters

    aClass

    The QCPlugIn subclass.

    Discussion

    You call this method only if the code for your custom patch is mixed with your application code, and you plan only to use the custom patch from within your application.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Returns and array of property port keys in the order you want them to appear in the user interface.

    Declaration

    Swift

    class func sortedPropertyPortKeys() -> [AnyObject]!

    Objective-C

    + (NSArray *)sortedPropertyPortKeys

    Return Value

    The property port keys in the order you want them to appear in the user interface.

    Discussion

    Override this method to specify an optional ordering for property based ports in the user interface.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Attributes for custom patches.

    Declaration

    Swift

    let QCPlugInAttributeNameKey: NSString! let QCPlugInAttributeDescriptionKey: NSString!

    Objective-C

    extern NSString* const QCPlugInAttributeNameKey; extern NSString* const QCPlugInAttributeDescriptionKey; extern NSString* const QCPlugInAttributeCopyrightKey;

    Constants

    • QCPlugInAttributeNameKey

      QCPlugInAttributeNameKey

      The key for the custom patch name. The associated value is an NSString object.

      Available in OS X v10.5 and later.

    • QCPlugInAttributeDescriptionKey

      QCPlugInAttributeDescriptionKey

      The key for the custom patch description. The associated value is an NSString object.

      Available in OS X v10.5 and later.

    • QQCPlugInAttributeCopyrightKey

      QQCPlugInAttributeCopyrightKey

      The key for the custom patch copyright information. The associated value is an NSString object.

  • Attributes for input and output ports.

    Declaration

    Swift

    let QCPortAttributeTypeKey: NSString! let QCPortAttributeNameKey: NSString! let QCPortAttributeMinimumValueKey: NSString! let QCPortAttributeMaximumValueKey: NSString! let QCPortAttributeDefaultValueKey: NSString! let QCPortAttributeMenuItemsKey: NSString!

    Objective-C

    extern NSString* const QCPortAttributeTypeKey; extern NSString* const QCPortAttributeNameKey; extern NSString* const QCPortAttributeMinimumValueKey; extern NSString* const QCPortAttributeMaximumValueKey; extern NSString* const QCPortAttributeDefaultValueKey; extern NSString* const QCPortAttributeMenuItemsKey;

    Constants

    • QCPortAttributeTypeKey

      QCPortAttributeTypeKey

      The key for the port type. The associated value can be of any of the following constants: QCPortTypeBoolean, QCPortTypeIndex, QCPortTypeNumber, QCPortTypeString, QCPortTypeColor, QCPortTypeImage, or QCPortTypeStructure.

      Available in OS X v10.4 and later.

    • QCPortAttributeNameKey

      QCPortAttributeNameKey

      The key for the port name. The associated value is an NSString object.

      Available in OS X v10.4 and later.

    • QCPortAttributeMinimumValueKey

      QCPortAttributeMinimumValueKey

      The key for the port minimum value. The associated value is an NSNumber object that specifies the minimum numerical value accepted by the port.

      Available in OS X v10.4 and later.

    • QCPortAttributeMaximumValueKey

      QCPortAttributeMaximumValueKey

      The key for the port maximum value. The associated value is an NSNumber object that specifies the maximum numerical value accepted by the port.

      Available in OS X v10.4 and later.

    • QCPortAttributeDefaultValueKey

      QCPortAttributeDefaultValueKey

      The key for the port default value. You can use this key only for value ports (Boolean, Index, Number, Color and String).

      Available in OS X v10.5 and later.

    • QCPortAttributeMenuItemsKey

      QCPortAttributeMenuItemsKey

      The key for the menu items. The associated value is an array of strings that are displayed in the user interface as a pop-up menu when the user double-clicks a port, as shown for the Blending input port of the Billboard patch. You can use this key only for an index port.image: ../Art/menu_items.pdf

      Available in OS X v10.5 and later.

  • Data types for input and output ports.

    Declaration

    Swift

    let QCPortTypeBoolean: NSString! let QCPortTypeIndex: NSString! let QCPortTypeNumber: NSString! let QCPortTypeString: NSString! let QCPortTypeColor: NSString! let QCPortTypeImage: NSString! let QCPortTypeStructure: NSString!

    Objective-C

    extern NSString* const QCPortTypeBoolean; extern NSString* const QCPortTypeIndex; extern NSString* const QCPortTypeNumber; extern NSString* const QCPortTypeString; extern NSString* const QCPortTypeColor; extern NSString* const QCPortTypeImage; extern NSString* const QCPortTypeStructure;

    Constants

    • QCPortTypeBoolean

      QCPortTypeBoolean

      The port type for a Boolean value. The associated value can be an NSNumber object or any object that responds to the -intValue, -floatValue, or -doubleValue methods.

      Available in OS X v10.4 and later.

    • QCPortTypeIndex

      QCPortTypeIndex

      The port type for an index value. The associated value can be an NSNumber object or any object that responds to the -intValue, -floatValue, or -doubleValue methods.

      Available in OS X v10.4 and later.

    • QCPortTypeNumber

      QCPortTypeNumber

      The port type for a number value. The associated value can be an NSNumber object or any object that responds to the -intValue, -floatValue, or -doubleValue methods.

      Available in OS X v10.4 and later.

    • QCPortTypeString

      QCPortTypeString

      The port type for a string. The associated value can be an NSString object or any object that responds to the -stringValue or -description methods.

      Available in OS X v10.4 and later.

    • QCPortTypeColor

      QCPortTypeColor

      The port type for a color value. The associated value must be an NSColor object.

      Available in OS X v10.4 and later.

    • QCPortTypeImage

      QCPortTypeImage

      The port type for an image. The associated value can be an NSImage object or a CIImage object.

      Available in OS X v10.4 and later.

    • QCPortTypeStructure

      QCPortTypeStructure

      The port type for an array, dictionary, or other structure, such as an NSArray or NSDictionary object.

      Available in OS X v10.4 and later.

  • Supported image pixel formats.

    Declaration

    Swift

    let QCPlugInPixelFormatARGB8: NSString! let QCPlugInPixelFormatBGRA8: NSString! let QCPlugInPixelFormatRGBAf: NSString! let QCPlugInPixelFormatI8: NSString! let QCPlugInPixelFormatIf: NSString!

    Objective-C

    extern NSString* const QCPlugInPixelFormatARGB8; extern NSString* const QCPlugInPixelFormatBGRA8; extern NSString* const QCPlugInPixelFormatRGBAf; extern NSString* const QCPlugInPixelFormatI8; extern NSString* const QCPlugInPixelFormatIf;

    Constants

    • QCPlugInPixelFormatARGB8

      QCPlugInPixelFormatARGB8

      An ARGB8 format. The alpha component is stored in the most significant bits of each pixel. Each pixel component is 8 bits. For best performance, use this format on PowerPC-based Macintosh computers, as it represents of the order of the data in memory.

      Available in OS X v10.5 and later.

    • QCPlugInPixelFormatBGRA8

      QCPlugInPixelFormatBGRA8

      A BGRA8 format. The alpha component is stored in the least significant bits of each pixel. Each pixel component is 8 bits. For best performance, use this format on Intel-PC-based Macintosh computers, as it represents of the order of the data in memory.

      Available in OS X v10.5 and later.

    • QCPlugInPixelFormatRGBAf

      QCPlugInPixelFormatRGBAf

      An RGBAf format. Pixel components are represented as floating-point values.

      Available in OS X v10.5 and later.

    • QCPlugInPixelFormatI8

      QCPlugInPixelFormatI8

      An I8 format. Intensity information is represented as an 8-bit value.

      Available in OS X v10.5 and later.

    • QCPlugInPixelFormatIf

      QCPlugInPixelFormatIf

      An If format. Intensity information is represented as a floating-point value.

      Available in OS X v10.5 and later.

  • Arguments to the method execute:atTime:withArguments:.

    Declaration

    Swift

    let QCPlugInExecutionArgumentEventKey: NSString! let QCPlugInExecutionArgumentMouseLocationKey: NSString!

    Objective-C

    extern NSString* const QCPlugInExecutionArgumentEventKey; extern NSString* const QCPlugInExecutionArgumentMouseLocationKey;

    Constants

    • QCPlugInExecutionArgumentEventKey

      QCPlugInExecutionArgumentEventKey

      The current NSEvent if available.

      Available in OS X v10.5 and later.

    • QCPlugInExecutionArgumentMouseLocationKey

      QCPlugInExecutionArgumentMouseLocationKey

      The current location of the mouse (as an NSPoint object stored in an NSValue object) in normalized coordinates relative to the OpenGL context viewport ([0,1]x[0,1] with the origin (0,0) at the lower-left corner).

      Available in OS X v10.5 and later.

  • Execution modes for custom patches.

    Declaration

    Swift

    struct QCPlugInExecutionMode { init(_ value: UInt32) var value: UInt32 }

    Objective-C

    typedef enum { kQCPlugInExecutionModeProvider = 1, kQCPlugInExecutionModeProcessor, kQCPlugInExecutionModeConsumer } QCPlugInExecutionMode;

    Constants

    • kQCPlugInExecutionModeProvider

      kQCPlugInExecutionModeProvider

      A provider execution mode. The custom patch executes on demand—that is, whenever data is requested of it, but at most once per frame.

      Available in OS X v10.5 and later.

    • kQCPlugInExecutionModeProcessor

      kQCPlugInExecutionModeProcessor

      A processor execution mode. The custom patch executes whenever its inputs change or if the time change (assuming it's time-dependent).

      Available in OS X v10.5 and later.

    • kQCPlugInExecutionModeConsumer

      kQCPlugInExecutionModeConsumer

      A consumer execution mode. The custom patch always executes assuming the value of its Enable input port is true. (The Enable port is automatically added by the system.)

      Available in OS X v10.5 and later.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.

  • Time modes for custom patches.

    Declaration

    Swift

    struct QCPlugInTimeMode { init(_ value: UInt32) var value: UInt32 }

    Objective-C

    typedef enum { kQCPlugInTimeModeNone = 0, kQCPlugInTimeModeIdle, kQCPlugInTimeModeTimeBase } QCPlugInTimeMode;

    Constants

    • kQCPlugInTimeModeNone

      kQCPlugInTimeModeNone

      No time dependency. The custom patch does not depend on time at all. (It does not use the time parameter of the execute:atTime:withArguments: method.)

      Available in OS X v10.5 and later.

    • kQCPlugInTimeModeIdle

      kQCPlugInTimeModeIdle

      An idle time dependency. The custom patch does not depend on time but needs the system to execute it periodically. For example if the custom patch connects to a piece of hardware, to ensure that it pulls data from the hardware, you would set the custom patch time dependency to idle time mode. This time mode is typically used with providers.]]

      Available in OS X v10.5 and later.

    • kQCPlugInTimeModeTimeBase

      kQCPlugInTimeModeTimeBase

      A time base dependency. The custom patch does depend on time explicitly and has a time base defined by the system. (It uses the time parameter of the execute:atTime:withArguments: method.)

      Available in OS X v10.5 and later.

    Import Statement

    Objective-C

    @import Quartz;

    Swift

    import Quartz

    Availability

    Available in OS X v10.5 and later.