FxImageColorInfo Enumeration

The new FxImageColorInfo enumerated type identifies some basic color properties of an FxImage. For YUV images, this enumeration tells you whether you should use the Rec. 601 or Rec. 709 color matrix to convert an image to RGB. For RGB images, it describes the gamma level of the image.

Xcode Template Location

FxPlug 1.2.2 SDK installs its Xcode templates in the location expected by Xcode 2.5 and later. Symbolic links are installed into the legacy location, so you can still open the templates using an earlier version of Xcode.

Parameter Value Retrieval

Plug-ins can now evaluate their parameter values at any time during -parameterChanged, or from within custom UI code. Previously, parameters could be evaluated at any time during -renderOutput, but otherwise only at the current time.

Collapsible Groups

Parameter groups now contain disclosure triangles that allow a group to be collapsed and expanded. The kFxParameterFlag_COLLAPSED flag is also respected; plug-ins can use this flag to create groups that are initially collapsed, or to programmatically collapse or expand groups in response to other parameter changes.

Start Point, End Point and Reverse Transitions

The start point, end point, and reverse controls in the Transition Viewer are now respected when rendering FxPlug transitions. These three controls affect the time fraction passed to the transition's render method; the reverse control also swaps the A and B images. You should not have to change your plug-in to take advantage of these controls.

Undo and Copy/Paste Crashes

Fixed a bug that could result in crashes when undoing the addition of a filter, or when copying and pasting filters.

Nested Groups

Hiding and disabling groups now work correctly with nested groups. However, there is still no visual indication that the groups are nested.

YUV Images

Plug-ins can use the new FxImageColorInfo API to determine if a YUV image is Rec. 601 or Rec. 709. This allows for improved YUV support, or accurate conversion to high-precision RGB within the plug-in.

FxTemporalTransitionImage

Previously, the FxTemporalTransitionImageAPI interpreted the times passed as relative to the requested source clip. Now the times are interpreted as relative to the transition item. This is consistent with all other uses of time in Final Cut Pro.

Multiple Monitors

Fixed a bug where custom UI could appear in the wrong location if the filter viewer was dragged to a second monitor.

Legacy Non-Real-Time Display Path

Fixed a bug where input images in the legacy non-real-time display path were not tagged with the correct aspect ratio.

Transition Input images now have the correct field order

Fixed a bug where input images for transitions were not labeled with the correct field order.

Hidden Groups

Final Cut Pro no longer ignores the kFxParameterFlag_HIDDEN flag when creating groups. However, groups must be disabled after the parameters they contain have been added.

Custom Control Saving

Previously, when a user changed a document with a custom control, Motion did not flag the document as changed and could close it without saving the changes. Motion now properly flags the document as changed. It also fixes a crash that could occur during an undo.

Image Well Gamma Shift

When you retrieve a bitmap from an image well parameter, the image now has the proper gamma setting that matches the gamma setting it would have if you had dropped it directly into the timeline.

API Object Refactoring

The various API Objects have been refactored to make them accessible at more times and to reduce the number of thread related problems. Plug-in developers should test to be sure that the APIs all still work as expected.

Interpolation for Up-sampling

Motion now uses interpolation rather than line doubling to up-sample fields to frame size.

3D Support

Motion only: Plug-ins can use the new Fx3DAPI protocol to get the 3D transforms for the camera and for the plug-in's layer.

Versioning Support

Plug-ins that include a version key in their Info.plist files can use the new FxVersioningAPI protocol to determine what version of their plug-in was used when a project was created.

Angle Units

For angle parameters, -getFloatValue and -setFloatValue now use degrees in all host applications.

Correct Duration for Transition Effects

The method [FxTimingAPI durationForEffect] returns the correct duration of FxPlug transition effects.

Correct Start Time and Duration for Untrimmed Media

The methods [FxTimingAPI startTimeOfImageParm] and [FxTimingAPI durationOfImageParm]return the correct start time and duration for image parameters, even if the media in the image wells do not have in and out points set.

Group Parameters Can Be Hidden

The kFxParameterFlag_HIDDEN flag works correctly with group start and end markers.

Parameter List No Longer Scrolls Inappropriately

Hiding or showing a parameter no longer causes the parameter list to scroll to the top.

No Artifacts in Parameter List

Hiding a parameter no longer causes a spurious horizontal line to be drawn in the parameter list.

Correct Channel Order

Previously, the output images for RGB-only generators would be labeled as RGBA, but the results would be interpreted as ARGB in 8-bit. The images are now correctly labeled as ARGB in 8-bit and RGBA in float.

No Gamma Shift

Retrieving bitmap images using the temporal image API no longer causes a gamma shift in the retrieved image.

Correct Rendering

Retrieving bitmap images from a group no longer causes the group to render upside down.

Correct Memory Management

Motion now properly releases custom NSViews when a filter is deleted.

Proper Bit Setting

Retrieving bitmap images from 16-bit per channel footage now returns proper 32-bit per channel footage.

Avoid Unnecessary Rendering

Repeated renders are no longer queued up when a custom control calls -startAction and -endAction during its -drawRect: method. This keeps the control and the current frame from constantly re-rendering.

Fix Crash Bug

Motion no longer crashes under certain circumstances when calling -currentTime: in the FxCustomParameterActionAPI protocol.

Parameters Updated Correctly

Parameters are now properly updated in the inspector when their enabled-disabled or hidden-shown state is changed.

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 1.2 SDK.

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: The 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

An [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.

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.

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’s 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 Pro 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 Pro 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 key-framed 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.

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, FxTimingAPI and FxTemporalImageAPI only work correctly if called during one of the following selectors:

• -getOutputWidth: height: 

• -frameSetup

• -renderOutput

• -frameCleanup

As well, sampling key-framed parameters at arbitrary times only works during these selectors.

Now Notifying Parameter Changes

Motion 2.1 did not call -parameterChanged: when the value of a compound parameter (for example, 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.