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.h
Returns 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.h
Returns 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.h
Loads 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.h
Returns 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.h
Registers 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.h
Returns 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.h
Returns 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.h
Adds 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.h
Adds 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.h
Creates 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.h
Returns 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.h
Allows 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.h
Allows 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.h
Performs 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.h
Removes 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.h
Removes 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.h
Provides 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.h
Provides 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.h
Sets 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.h
Allows 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.h
Allows 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.h
Returns 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.h
Attributes for custom patches.
extern NSString* const QCPlugInAttributeNameKey; extern NSString* const QCPlugInAttributeDescriptionKey; extern NSString* const QCPlugInAttributeCopyrightKey;
QCPlugInAttributeNameKey
The 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
.
QCPlugInAttributeDescriptionKey
The 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
.
QQCPlugInAttributeCopyrightKey
The key for the custom patch copyright information. The associated value is an NSString
object.
QCPlugIn.h
Attributes 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;
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 Mac OS X v10.4 and later.
Declared in QCPlugIn.h
.
QCPortAttributeNameKey
The 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
.
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 Mac OS X v10.4 and later.
Declared in QCPlugIn.h
.
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 Mac OS X v10.4 and later.
Declared in QCPlugIn.h
.
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 Mac OS X v10.5 and later.
Declared in QCPlugIn.h
.
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.
Available in Mac OS X v10.5 and later.
Declared in QCPlugIn.h
.
QCPlugIn.h
Data 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;
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 Mac OS X v10.4 and later.
Declared in QCPlugIn.h
.
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 Mac OS X v10.4 and later.
Declared in QCPlugIn.h
.
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 Mac OS X v10.4 and later.
Declared in QCPlugIn.h
.
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 Mac OS X v10.4 and later.
Declared in QCPlugIn.h
.
QCPortTypeColor
The 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
.
QCPortTypeImage
The 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
.
QCPortTypeStructure
The 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.h
Supported image pixel formats.
extern NSString* const QCPlugInPixelFormatARGB8; extern NSString* const QCPlugInPixelFormatBGRA8; extern NSString* const QCPlugInPixelFormatRGBAf; extern NSString* const QCPlugInPixelFormatI8; extern NSString* const QCPlugInPixelFormatIf;
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 Mac OS X v10.5 and later.
Declared in QCPlugIn.h
.
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 Mac OS X v10.5 and later.
Declared in QCPlugIn.h
.
QCPlugInPixelFormatRGBAf
An RGBAf format. Pixel components are represented as floating-point values.
Available in Mac OS X v10.5 and later.
Declared in QCPlugIn.h
.
QCPlugInPixelFormatI8
An I8 format. Intensity information is represented as an 8-bit value.
Available in Mac OS X v10.5 and later.
Declared in QCPlugIn.h
.
QCPlugInPixelFormatIf
An 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.h
Arguments to the method execute:atTime:withArguments:
.
extern NSString* const QCPlugInExecutionArgumentEventKey; extern NSString* const QCPlugInExecutionArgumentMouseLocationKey;
QCPlugInExecutionArgumentEventKey
The current NSEvent
if available.
Available in Mac OS X v10.5 and later.
Declared in QCPlugIn.h
.
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 Mac OS X v10.5 and later.
Declared in QCPlugIn.h
.
QCPlugIn.h
Execution modes for custom patches.
typedef enum { kQCPlugInExecutionModeProvider = 1, kQCPlugInExecutionModeProcessor, kQCPlugInExecutionModeConsumer } QCPlugInExecutionMode;
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 Mac OS X v10.5 and later.
Declared in QCPlugIn.h
.
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 Mac OS X v10.5 and later.
Declared in QCPlugIn.h
.
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 Mac OS X v10.5 and later.
Declared in QCPlugIn.h
.
QCPlugIn.h
Time modes for custom patches.
typedef enum { kQCPlugInTimeModeNone = 0, kQCPlugInTimeModeIdle, kQCPlugInTimeModeTimeBase } QCPlugInTimeMode;
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 Mac OS X v10.5 and later.
Declared in QCPlugIn.h
.
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 Mac OS X v10.5 and later.
Declared in QCPlugIn.h
.
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 Mac OS X v10.5 and later.
Declared in QCPlugIn.h
.
QCPlugIn.h
© 2008 Apple Inc. All Rights Reserved. (Last updated: 2008-04-08)