Advanced Search

Log In | Not a Member?

Contact ADC

< Previous PageNext Page > Hide TOC

API Overview

In this section:

Protocols
Properties
Parameters
Rendering
Images
Parameter Interaction
Custom Parameter UI
On-Screen Controls
Host Capabilities

Protocols

The primary protocols defined by the FxPlug SDK are FxFilter, FxGenerator, and FxTransition. Each plug-in conforms to one of these protocols. For more information about the methods in these protocols, see the reference documentation for the header files FxFilter.h, FxGenerator.h, and FxTransition.h. Note that these protocols inherit methods from a superprotocol FxBaseEffect, which is defined in FxBaseEffect.h.

Properties

The FxPlug SDK 1.1 introduced the plug-in properties dictionary. One of the methods defined by the new FxBaseEffect protocol was -properties. From this method, a plug-in returns an NSDictionary with key-value pairs that describe the capabilities of a plug-in.

Parameters

Once a plug-in is applied, the host application asks for its parameter list by calling the -addParameters method. This method is declared in the FxBaseEffect protocol, which is inherited by the FxGenerator, FxFilter, and FxTransition protocols. The host application then displays the parameters with the appropriate UI.

In the -addParameters method, a plug-in adds its parameters, one by one, using methods in the FxParameterCreation protocol. First, the plug-in calls the -apiForProtocol: method, defined by the PluginManager framework, to obtain the host’s API object that implements the protocol. Then it calls the parameter creation methods to add the parameters. For example, this is an -addParameters method from a simple opacity filter:

-(  BOOL  ) addParameters

{

   id  <FxParameterCreation> paramsApi =

   [_apiManager apiForProtocol:@protocol(FxParameterCreationAPI)];

   if  ( paramsApi != NULL  )

   {

       [paramsApi addFloatSliderWithName:@"Opacity"

                            parmId:  OPACITY_ID

                      defaultValue:  1.0

                      parameterMin:  0.0

                      parameterMax:  3.0

                         sliderMin:  0.0

                         sliderMax:  1.0

                             delta:  0.01

                         parmFlags:  kFxParameterFlag_DEFAULT];

        return YES;

    }

    else

         return NO;

}

You can find more information about adding parameters in the reference documentation for the header files FxParameterAPI.h, FxOptionalParameterAPI.h, and FxOptionalParameterAPI.h.

Protocols in these headers include 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

There are also optional parameters that may be supported by some host applications but not by others:

• Histogram

• Gradient

In addition to the standard parameter types, you may create a custom parameter with an opaque data type, using the method:

• -addCustomParameterWithName:parmId:defaultValue:parmFlags

Each custom parameter must be associated with a custom parameter view, which is defined by the methods in FxCustomParameterUI.h. More details about custom parameter UI can be found in the reference documentation.

Other protocols in these headers include accessor methods for getting and setting parameter values.

Rendering

In order to render an output frame for a filter plug-in, the host application calls the following sequence of plug-in methods:

    -(BOOL)frameSetup:(FxRenderInfo)renderInfo

        inputInfo:(FxImageInfo)inputInfo

        hardware:(BOOL*)canRenderHardware

        software:(BOOL*)canRenderSoftware;

    -(BOOL)renderOutput:(FxImage *)output

        withInput:(FxImage*)inputImage

        withInfo:(FxRenderInfo)renderInfo;

    -(BOOL)frameCleanup;

Generator and transition plug-ins render with a similar sequence, but with different numbers of inputs passed to their -frameSetup and -renderOutput methods.

In its implementation of the method -renderOutput:...withInfo: , a plug-in requests parameter values and renders an output frame. The output object is an instance of one of two subclasses of the FxImage class: FxBitmap or FxTexture.

Images

In its implementation of the method -frameSetup:, a plug-in specifies whether it can render in software on the CPU, in hardware on the GPU, or in both. If the plug-in requests both kinds of rendering, the host application decides which to use. For example, Motion is more likely to choose a hardware path, while Final Cut Pro tends to prefer software rendering.

When rendering in software, input and output images are FxBitmap objects; in hardware, FxTexture objects. You can find more information about these image classes in the reference documentation for the header files FxImage.h, FxBitmap.h, and FxTexture.h.

Parameter Interaction

When a user changes a parameter control for an FxPlug plug-in, the host application calls the plug-in method -parameterChanged:. In response, the plug-in can change the state of other parameters. For example, if the value of a toggle button changes, the plug-in can hide or reveal other parameter controls, or change their values.

Custom Parameter UI

For a custom UI parameter, user interaction is handled differently. In this case,the plug-in conforms to theFxParameterViewHost protocol by implementing a -createViewForParm: method, to provide an NSView subclass to the host app. Like any other NSView subclass, that custom view draws itself in a window, and receives notification of user actionssuch as mouse, key, and tablet events.

In response to user events, a plug-in custom view can notify the host application that a parameter value has changed. A plug-in can create a custom view object programmatically, or may retrieve it from a NIB file created in Interface Builder and placed in the plug-in’s Resources folder.

On-Screen Controls

In addition to standard and custom parameter UI, a plug-in can also implement custom on-screen controls that are composited directly onto the host application’s canvas window using OpenGL. Examples of on-screen controls can be found in the SimplePaint example (/Developer/Examples/FxPlug) and in some of Motion’s built-in filters such as Kaleidoscope and Basic 3D.

To create an on-screen control, you create a second ProPlug plug-in class that conforms to the FxOnScreenControl protocol. You package this class in the same bundle as its associated filter, generator, or transition plug-in.

Host Capabilities

A new class in FxPlug 1.1 defines methods that your plug-in can use to identify key capabilities in the host application. The FxHostCapabilities class is specified in the new header file FxHostCapabilities.h. Using the methods in this class, you can tailor the behavior of your plug-in to the context in which it is operating. Example methods include -upscalesFields and -supportsHiddenParameters. For more details, see the reference documentation for the FxHostCapabilities.h header.

Note that this new class was not implemented in earlier versions of the FxPlug framework. If you reference the FxHostCapabilities symbol in your plug-in, the plug-in will only link if the version of the installed FxPlug framework is 1.1 or later. Your plug-in installer should check that FxPlug 1.1 or later is present. (If it’s not, you can alert the user to run Software Update). Alternatively, you can retrieve the class by name using a string literal, as in this example:

Class class = NSClassFromString( @"FxHostCapabilities" );

id hostCaps = [[class alloc] initWithAPIManager:_apiManager];

if ( ![hostCaps supportsDisabledParameters] )

    ; // Do something

< Previous PageNext Page > Hide TOC

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice