Adding Parameters to Plug-ins

Once a plug-in is invoked by a host application, the host application asks for the plug-in’s parameter list by calling the -addParametersWithError: method. This method is declared in the FxBaseEffect protocol, which is inherited by the FxTileableEffect protocol. The host application then displays the parameters in its inspector.

The FxPlug SDK includes methods for adding these standard types of parameters:

• Floating-point slider

• Integer slider

• Angle slider

• Toggle button (checkbox)

• RGB color

• RGBA color

• Point

• Popup menu

• Image Reference

• Group start

• Group end

• String

• Histogram

• Gradient

In the -addParametersWithError: method, a plug-in first calls the apiForProtocol: method (defined by the PluginManager framework) to get the host API object that implements the protocol. It then adds parameters, one by one, using methods in the FxParameterCreationAPI_v5 protocol.

For example, the following code shows an -addParametersWithError: method from a simple opacity filter:

enum 
{ 
kOpacityID = 1
}; 

- (BOOL)addParametersWithError:(NSError**)error
{
    id<FxParameterCreationAPI_v5> paramAPI = [apiManager apiForProtocol:@protocol(FxParameterCreationAPI_v5)];

    BOOL success =[paramAPI addFloatSliderWithName:@"Opacity"
                                       parameterId:kOpacityID
                                      defaultValue:1.0
                                      parameterMin:0.0
                                      parameterMax:100.0
                                         sliderMin:0.0
                                         sliderMax:10.0
                                             delta:0.1 
                                    parameterFlags:kFxParameterFlag_DEFAULT];
    return success;
} 

In addition to the standard parameter types, you can use the following method to create a custom parameter with an opaque data type:

-addCustomParameterWithName:parameterID:defaultValue:parameterFlags

Each custom parameter must be associated with a custom parameter view, which is defined by the methods in FxCustomParameterViewHost_v2.

When a user changes a parameter control for an FxPlug plug-in, the host application calls the -parameterChanged:atTime:error: plug-in method. This is useful for a plug-in that changes the state of other parameters. For example, if the user changes a toggle button, the plug-in can hide or reveal other parameters during -parameterChanged:atTime:error:.

Custom UI parameters let developers draw directly to a custom UI and create their own controls in a space that the host application makes for them in the inspector. The host application handles user interaction for custom parameters in a different way than standard UI parameters. For example, when you develop custom parameters, they must conform to the FxCustomParameterViewHost_v2 protocol. An example of this can be found in the FxSimpleColorCorrector sample plug-in.

In your plug-in, custom parameters conform to the FxParameterViewHost protocol by implementing a -createViewForParameterID: method that provides an NSView subclass to the host app. Like any other NSView subclass, this custom view draws itself in a window and receives notification of any user actions such as mouse, key, and tablet events. In response to user events, the custom view sets parameter values. Usually it sets the value of a custom parameter. The host application notices that a parameter value has changed and calls the plug-in to render with the new parameter values.

The plug-in can create a custom view object programmatically or retrieve it from a XIB file (created in Xcode’s Interface Builder and placed in your plug-in’s Resources folder).

Your plug-in’s custom view methods must call the FxCustomParameterActionAPI_v4 host API —startAction: method before your plug-in accesses any parameter values, and then call the -endAction: method after it has finished accessing the parameter values. This lets the host application set up and restore the internal state.

As you develop plug-ins over time, you may need to deprecate, add, or update your parameters, like changing a default value or range.

To ensure that projects using your older plug-ins still function correctly, use FxVersioningAPI to find out the version of the plug-in that’s used with a project. With this information, you can branch your parameter code, update your project, and handle special cases as needed.

For example, if you create a version 1 brightness filter with a floating point slider and apply it to a project, the project saves the plug-in’s version number along with the slider value. On subsequent launches of the project, you can query versionAtCreation and check for a version number of 1.