| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Quartz.framework/Frameworks/QuartzComposer.framework |
| Availability | Available in Mac OS X v10.5 and later. |
| Declared in | QCPlugIn.h QCPlugInViewController.h |
| Companion guides |
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.
– addInputPortWithType:forKey:withAttributes:
– removeInputPortForKey:
– addOutputPortWithType:forKey:withAttributes:
– removeOutputPortForKey:
Returns a dictionary that contains strings for the user interface that describe the custom patch.
+ (NSDictionary*) attributes
The dictionary can contain one or more of these keys along with the appropriate string: QCPlugInAttributeNameKey, QCPlugInAttributeDescriptionKey, and QQCPlugInAttributeCopyrightKey.
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.

QCPlugIn.hReturns a dictionary that contains strings for the user interface that describe the optional attributes for ports created from properties.
+ (NSDictionary*) attributesForPropertyPortWithKey:(NSString*)key
The name of the property.
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.”
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.
QCPlugIn.hReturns the execution mode of the custom patch.
+ (QCPlugInExecutionMode) executionMode
The execution mode of the custom patch. See “Execution Modes” for the constants you can return.
You must implement this method to define whether your custom patch is a provider, a processor, or a consumer.
QCPlugIn.hLoads a Quartz Composer plug-in bundle from the specified path.
+ (BOOL) loadPlugInAtPath:(NSString*)path
The location of the bundle.
YES if successful.
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.
QCPlugIn.hReturns the keys for the internal settings of a custom patch.
+ (NSArray*) plugInKeys
An array of keys used for key-value coding (KVC) of the internal settings.
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]; |
} |
QCPlugIn.hRegisters a QCPlugIn subclass.
+ (void) registerPlugInClass:(Class)aClass
The QCPlugIn subclass.
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.
QCPlugIn.hReturns and array of property port keys in the order you want them to appear in the user interface.
+ (NSArray*) sortedPropertyPortKeys;
The property port keys in the order you want them to appear in the user interface.
Override this method to specify an optional ordering for property based ports in the user interface.
QCPlugIn.hReturns the time mode for the custom patch.
+ (QCPlugInTimeMode) timeMode
The time mode of the custom patch. See “Time Modes” for the constants you can return.
You must implement this method to define whether you custom patch depends on time, doesn’t depend on time, or needs time to idle.
QCPlugIn.hAdds an input port of the specified type and associates a key and attributes with the port.
- (void) addInputPortWithType:(NSString*)type forKey:(NSString*)key withAttributes:(NSDictionary*)attributes
The port type. See “Port Input and Output Types”.
The key to associate with the port.
A dictionary of attributes for the port. See “Input and Output Port Attributes”. Although the dictionary is optional, it’s recommended that provide attributes 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. (See attributesForPropertyPortWithKey:.) Pass nil if you do not want to provide attributes.
This method throws an exception if called from within the execute:atTime:withArguments: method or if there's already an input or output port with that key.
QCPlugIn.hAdds an output port of the specified type and associates a key and attributes with the port.
- (void) addOutputPortWithType:(NSString*)type forKey:(NSString*)key withAttributes:(NSDictionary*)attributes
The port type. See “Port Input and Output Types”.
The key to associate with the port.
A dictionary of attributes for the port. See “Input and Output Port Attributes”. Although the dictionary is optional, it’s recommended that provide attributes 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. (See attributesForPropertyPortWithKey:.) Pass nil if you do not want to provide attributes.
This method throws an exception if called from within the execute:atTime:withArguments: method or if there is already an output port with that key.
QCPlugIn.hCreates and returns a view controller for the Settings pane of a custom patch.
- (QCPlugInViewController*) createViewController
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.
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"]; |
} |
QCPlugInViewController.hReturns whether the input port value changed since the last execution of the custom patch.
- (BOOL) didValueForInputKeyChange:(NSString*)key
The key for the input port whose value you want to check.
YES if the value on the input port changed since the last time the execute:atTime:withArguments: method was called; always returns NO if called outside of the execute:atTime:withArguments: method.
QCPlugIn.hAllows you to perform custom tasks when the execution of the QCPlugIn object is paused.
- (void) disableExecution:(id<QCPlugInContext>)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.
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.
QCPlugIn.hAllows you to perform custom tasks when the execution of the QCPlugIn object is resumed.
- (void) enableExecution:(id<QCPlugInContext>)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.
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.
QCPlugIn.hPerforms the processing or rendering tasks appropriate for the custom patch.
- (BOOL) execute:(id<QCPlugInContext>)context atTime:(NSTimeInterval)time withArguments:(NSDictionary*)arguments
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.
The execution interval.
A dictionary of arguments that can be used during execution. See “Execution Arguments”.
NO indicates the custom patch was not able to execute successfully. In this case, the Quartz Composer engine stops rendering the current frame.
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.
QCPlugIn.hRemoves the input port for a given key.
- (void) removeInputPortForKey:(NSString*)key
The key associated with the port that you want to remove.
This method throws an exception if from within the execute:atTime:withArguments: method, if there is not an input port with that key, or if the port is created from a property.
QCPlugIn.hRemoves the output port for a given key.
- (void) removeOutputPortForKey:(NSString*)key
The key associated with the port that you want to remove.
This method throws an exception if called from within the execute:atTime:withArguments: method, if there is not an output port with that key, or if the port is created from a property.
QCPlugIn.hProvides custom serialization for patch internal settings that do not comply to the NSCoding protocol.
- (id) serializedValueForKey:(NSString*)key
The key for the value to retrieve.
Either nil or a value that’s compliant with property lists: NSString, NSNumber, NSDate, NSData, NSArray, or NSDictionary.
If your patch has internal settings that do not conform to the NSCoding protocol, you must implement this method.
QCPlugIn.hProvides custom deserialization for patch internal settings that were previously serialized using the method serializedValueForKey:.
- (void) setSerializedValue:(id)serializedValue forKey:(NSString*)key
The value to deserialize.
The key for the value to deserialize.
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.
QCPlugIn.hSets the value of an output port.
- (BOOL) setValue:(id)value forOutputKey:(NSString*)key
The key associated with the output port whose value you want to set.
YES if successful; NO if called outside of the execute:atTime:withArguments: method.
You call this method from within your execute:atTime:withArguments: method to set the output values of your custom patch.
QCPlugIn.hAllows you to perform custom setup tasks before the Quartz Composer engine starts rendering.
- (BOOL) startExecution:(id<QCPlugInContext>)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.
NO indicates a fatal error occurred and prevents the Quartz Composer engine from starting.
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.
QCPlugIn.hAllows you to perform custom tasks when the QCPlugIn object stops executing.
- (void) stopExecution:(id<QCPlugInContext>)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.
The Quartz Composer engine calls this method when it stops executing. You can optionally override this execution method to perform cleanup tasks.
QCPlugIn.hReturns the current value for an input port.
- (id) valueForInputKey:(NSString*)key
The key for the input port you want to check.
The value associated with the key or nil if called outside of the execute:atTime:withArguments: method.
You call this method from within your execute:atTime:withArguments: method to retrieve the input values of your custom patch.
QCPlugIn.hAttributes for custom patches.
extern NSString* const QCPlugInAttributeNameKey; extern NSString* const QCPlugInAttributeDescriptionKey; extern NSString* const QCPlugInAttributeCopyrightKey;
QCPlugInAttributeNameKeyThe key for the custom patch name. The associated value is an NSString object.
Available in Mac OS X v10.5 and later.
Declared in QCPlugIn.h.
QCPlugInAttributeDescriptionKeyThe key for the custom patch description. The associated value is an NSString object.
Available in Mac OS X v10.5 and later.
Declared in QCPlugIn.h.
QQCPlugInAttributeCopyrightKeyThe key for the custom patch copyright information. The associated value is an NSString object.
QCPlugIn.hAttributes for input and output ports.
extern NSString* const QCPortAttributeTypeKey; extern NSString* const QCPortAttributeNameKey; extern NSString* const QCPortAttributeDefaultValueKey; extern NSString* const QCPortAttributeMinimumValueKey; extern NSString* const QCPortAttributeMaximumValueKey; extern NSString* const QCPortAttributeDefaultValueKey; extern NSString* const QCPortAttributeMenuItemsKey;
QCPortAttributeTypeKeyThe 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 Mac OS X v10.4 and later.
Declared in QCPlugIn.h.
QCPortAttributeNameKeyThe key for the port name. The associated value is an NSString object.
Available in Mac OS X v10.4 and later.
Declared in QCPlugIn.h.
QCPortAttributeMinimumValueKeyThe 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 Mac OS X v10.4 and later.
Declared in QCPlugIn.h.
QCPortAttributeMaximumValueKeyThe 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 Mac OS X v10.4 and later.
Declared in QCPlugIn.h.
QCPortAttributeDefaultValueKeyThe key for the port default value. You can use this key only for value ports (Boolean, Index, Number, Color and String).
Available in Mac OS X v10.5 and later.
Declared in QCPlugIn.h.
QCPortAttributeMenuItemsKeyThe 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.
Available in Mac OS X v10.5 and later.
Declared in QCPlugIn.h.
QCPlugIn.hData types for input and output ports.
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;
QCPortTypeBooleanThe 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 Mac OS X v10.4 and later.
Declared in QCPlugIn.h.
QCPortTypeIndexThe 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 Mac OS X v10.4 and later.
Declared in QCPlugIn.h.
QCPortTypeNumberThe 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 Mac OS X v10.4 and later.
Declared in QCPlugIn.h.
QCPortTypeStringThe 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 Mac OS X v10.4 and later.
Declared in QCPlugIn.h.
QCPortTypeColorThe port type for a color value. The associated value must be an NSColor object.
Available in Mac OS X v10.4 and later.
Declared in QCPlugIn.h.
QCPortTypeImageThe port type for an image. The associated value can be an NSImage object or a CIImage object.
Available in Mac OS X v10.4 and later.
Declared in QCPlugIn.h.
QCPortTypeStructureThe port type for an array, dictionary, or other structure, such as an NSArray or NSDictionary object.
Available in Mac OS X v10.4 and later.
Declared in QCPlugIn.h.
QCPlugIn.hSupported image pixel formats.
extern NSString* const QCPlugInPixelFormatARGB8; extern NSString* const QCPlugInPixelFormatBGRA8; extern NSString* const QCPlugInPixelFormatRGBAf; extern NSString* const QCPlugInPixelFormatI8; extern NSString* const QCPlugInPixelFormatIf;
QCPlugInPixelFormatARGB8An 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 Mac OS X v10.5 and later.
Declared in QCPlugIn.h.
QCPlugInPixelFormatBGRA8A 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 Mac OS X v10.5 and later.
Declared in QCPlugIn.h.
QCPlugInPixelFormatRGBAfAn RGBAf format. Pixel components are represented as floating-point values.
Available in Mac OS X v10.5 and later.
Declared in QCPlugIn.h.
QCPlugInPixelFormatI8An I8 format. Intensity information is represented as an 8-bit value.
Available in Mac OS X v10.5 and later.
Declared in QCPlugIn.h.
QCPlugInPixelFormatIfAn If format. Intensity information is represented as a floating-point value.
Available in Mac OS X v10.5 and later.
Declared in QCPlugIn.h.
QCPlugIn.hArguments to the method execute:atTime:withArguments:.
extern NSString* const QCPlugInExecutionArgumentEventKey; extern NSString* const QCPlugInExecutionArgumentMouseLocationKey;
QCPlugInExecutionArgumentEventKeyThe current NSEvent if available.
Available in Mac OS X v10.5 and later.
Declared in QCPlugIn.h.
QCPlugInExecutionArgumentMouseLocationKeyThe 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 Mac OS X v10.5 and later.
Declared in QCPlugIn.h.
QCPlugIn.hExecution modes for custom patches.
typedef enum {
kQCPlugInExecutionModeProvider = 1,
kQCPlugInExecutionModeProcessor,
kQCPlugInExecutionModeConsumer
} QCPlugInExecutionMode;
kQCPlugInExecutionModeProviderA 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 Mac OS X v10.5 and later.
Declared in QCPlugIn.h.
kQCPlugInExecutionModeProcessorA processor execution mode. The custom patch executes whenever its inputs change or if the time change (assuming it's time-dependent).
Available in Mac OS X v10.5 and later.
Declared in QCPlugIn.h.
kQCPlugInExecutionModeConsumerA 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 Mac OS X v10.5 and later.
Declared in QCPlugIn.h.
QCPlugIn.hTime modes for custom patches.
typedef enum {
kQCPlugInTimeModeNone = 0,
kQCPlugInTimeModeIdle,
kQCPlugInTimeModeTimeBase
} QCPlugInTimeMode;
kQCPlugInTimeModeNoneNo 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 Mac OS X v10.5 and later.
Declared in QCPlugIn.h.
kQCPlugInTimeModeIdleAn 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 Mac OS X v10.5 and later.
Declared in QCPlugIn.h.
kQCPlugInTimeModeTimeBaseA 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 Mac OS X v10.5 and later.
Declared in QCPlugIn.h.
QCPlugIn.h
© 2008 Apple Inc. All Rights Reserved. (Last updated: 2008-04-08)