---

Features of FxPlug SDK 1.2

The focus of FxPlug SDK 1.2 is improved consistency between Motion and Final Cut Pro, and better support for timing information. In addition to the changes in the FxPlug framework itself, there are other FxPlug-related changes in Plug-in Manager 1.7, Final Cut Pro 6, and Motion 3.

In this section:

The FxPlug 1.2 Framework
Plug-in Manager 1.7
Final Cut Pro 6
Remaining Issues in Final Cut Pro 6
Motion 3

The FxPlug 1.2 Framework

Timing information

A FxTimingAPI protocol defines the methods provided by the host that allow a plug-in to query the timing properties of its input image(s), image parameters, effect, timeline, and in/out points. This protocol is the most significant change in FxPlug SDK 1.2.

Field and Field Order Information

FxImage objects now respond to -field and -fieldOrder accessors. These accessors provide information about fields in interlaced images: the field identifier for an image, and the field order of an image. The incorrectly named field FxRenderInfo.field has been renamed FxRenderInfo.fieldOrder. But you should use the FxImage accessors instead.

Progress and Cancellation

A FxProgressAPI protocol defines methods for plug-ins that render slowly to update a progress bar and support user cancellation.

Image Retiming in Transitions

Final Cut Pro only: A FxTemporalTransitionImageAPI protocol allows a plug-in to retrieve its A or B input images at different times. In FxPlug 1.1, retiming was only enabled for images from filter inputs and image wells, not for transition input images.

Absolute versus Relative Times

A [FxHostCapabilities timeBase] method allows a plug-in to determine whether the host application measures times as frame offsets from the start of the timeline, or from the start of a clip, generator, filter, or transition.

Getting Angle Values

The -getAngle:fromParm:atTime: method is deprecated. Plug-ins should use -getFloatValue: instead.

Plug-in Manager 1.7

Free Access to Host APIs

The Plug-in Manager no longer requires a plug-in Info.plist file to declare which host APIs the plug-in might use. However, for a plug-in to load on a system with an older version of the Plug-in Manager, the plug-in should still list these APIs in the ProPlugProtocolList—as illustrated by the example projects and Xcode templates.

Final Cut Pro 6

Support for Hidden and Disabled Parameters

Final Cut Pro 6 respects kFxParameterFlag_HIDDEN and kFxParameterFlag_DISABLED. A plug-in can specify these flags when it creates parameters, and change them dynamically with the -setParameterFlags: selector of FxParameterSettingAPI. 

Support for Non-Animatable Parameters

Final Cut 6 respects the kFxParameterFlag_NOT_ANIMATABLE flag if it is set when a parameter is created. A plug-in cannot change this flag dynamically once a parameter is created.

Support for Parameter Groups

Final Cut 6 provides some support for parameter groups. Parameter groups are implemented as labels separating the parameters, similar to After Effects plug-ins in Final Cut Pro. The groups cannot be collapsed or nested. 

Support for FxParameterSettingAPI

Final Cut Pro 5.1.2 did not implement the FxParameterSettingAPI and a plug-in could not set the values of its parameters after creation. Final Cut 6 supports this API. Plug-ins can now change the values of their parameters dynamically. For example, an effect might want to implement a “presets” functionality by changing some parameter values when the user makes a choice from a popup menu.

Parameters Sampled at Arbitrary Times 

A plug-in running under Final Cut Pro 5.1.2 could only sample parameters at the current render time. The only exception to this was image parameters. In Final Cut Pro 6, a plug-in can sample any type of parameter at any time. This allows an effect to examine the values of keyframed parameters at multiple times. 

Plug-ins Only Instantiated Once at Startup 

At startup, Final Cut Pro 5.1.2 instantiated each installed plug-in multiple times, sometimes sending the plug-in an -initWithAPIManager: message, sometimes sending the plug-in an -init message. At startup, Final Cut Pro 6 instantiates a plug-in once via -initWithAPIManager:, sends the instance the following messages:

• -addParameters

• -variesOverTime

• -properties

and releases the plug-in instance. 

Plug-ins No Longer Instantiated Multiple Times 

Final Cut Pro 5.1.2 created two instances of a plug-in when the plug-in was added to a timeline, using one instance for rendering and the other instance for parameter management. Final Cut Pro 6 creates one instance when a plug-in is added to a timeline and uses this single instance for both rendering and parameter management. 

Initial Value of Point Controls Respected

Final Cut Pro 5.1.2 always set the initial value of point controls at the center of the image. Final Cut Pro 6 uses the value specified by the plug-in.

Software Rendering Preferred in More Cases

Final Cut Pro 5.1.2 asked a plug-in to render on the GPU unless the plug-in returned canDoHardware = NO from -frameSetup. Final Cut Pro 6 asks a plug-in to render in software if: 

• The plug-in returns canDoSoftware=YES from -frameSetup

• AND

• The plug-in specifies kFxPropertyKey_SupportsRowBytes = YES

Otherwise, Final Cut Pro 6 asks the plug-in to render in hardware. 

Consistent Parameter Change Notification

Final Cut Pro 5.1.2 sent plug-ins the -parameterChanged: message only if the parameter change caused a render. If the playhead was not on the item with the effect, Final Cut Pro 5.1.2 did not send the message. Final Cut Pro 6 sends a plug-in this message immediately when a parameter changes, whether the change causes a render or not. 

Requesting a Nonexistent Parameter

In Final Cut Pro 5.1.2, a plug-in request for the value of a parameter that had not been added created an Objective-C exception and left Final Cut Pro in an inconsistent state. In Final Cut Pro 6, a request for a parameter that does not exist simply returns NO.

Output Pixel Aspect Ratio Reported Correctly

In Final Cut Pro 5.1.2, if an FxPlug effect was rendering in software and did not change the size of the output image, the output image would always have a pixel aspect ratio of 1.0. In Final Cut Pro 6, the pixel aspect ratio is reported correctly.

Remaining Issues in Final Cut Pro 6

No Support for Onscreen Controls

Final Cut Pro 6 does not support onscreen controls.

No Support for Resizing Output Images

Final Cut Pro 6 does not allow a filter to resize its output image. In addition, it no longer calls the -getOutputWidth:height: method.

Some APIs Available Only During Render 

In Final Cut Pro 6, the FxTimingAPI and FxTemporalImageAPI only work correctly if called during one of the following selectors: 

• -getOutputWidth: height: 

• -frameSetup

• -renderOutput

• -frameCleanup

As well, sampling keyframed parameters at arbitrary times only works during these selectors.

Motion 3

Now Notifying Parameter Changes

Motion 2.1 did not call -parameterChanged: when the value of a compound parameter (e.g. point, color, histogram, gradient) changed. Motion 3 does.

Fixed Pixel Aspect of Textures from Image Wells

Motion 2.1 did not provide the correct pixelAspect value for FxTexture images retrieved from image well parameters. Motion 3 corrects this problem.

Float Images pixelFormat Correction

Motion 2.1 ordered pixel components RGBA in floating-point images, but the -pixelFormat method returned ARGB. Motion 3 corrects this problem. You can determine whether floating-point images are mislabeled by querying [FxHostCapabilities formatsFloatRGBABitmapsAsARGB].

Temporal Image Retrieval for Image Wells

Motion 2.1 had problems retrieving images from image well parameters at arbitrary times. The resulting images were at incorrect times and upside-down. Motion 3 retrieves these images correctly.

Support for Non-Animated Parameters

Motion 3 adds support for the kFxParameterFlag_NOT_ANIMATABLE flag.

Scale Factor and Resizing Reconciled

Motion 3 corrects an issue in Motion 2.1 that produced incorrect results when resizing either via -getOutputWidth:height: or down-sampling for low quality render.

---