Next Previous

FxPlug Concepts and API

An FxPlug plug-in is an application bundle that interacts with a host application to extend its functionality.

When a plug-in needs to access host application functionality—such as requesting video stream information—it uses methods in a host API. A host API is an object, provided by the host application, that implements methods that can be called by a plug-in. It’s analogous to a callback suite in other plug-in architectures, but is implemented as an Objective-C protocol.

For example, the FxPlug SDK defines host protocols that include methods for requesting layer information, converting between canvas and object coordinate spaces, building a list of plug-in parameters, getting and setting parameter values, and evaluating input images at arbitrary times. Not all hosts are guaranteed to support all host-API protocols specified in FxPlug, so a plug-in must request the host API object before invoking its methods.

The principal frameworks in the FxPlug SDK are FxPlug.framework and PlugInManager.framework. These frameworks are located at /Library/Developer/Frameworks/.

Protocols

The primary protocols defined by the FxPlug SDK are FxFilter, FxGenerator, and FxOnScreenControl. All FxPlug plug-ins must conform to one of these protocols.

Host Protocols Versus Plug-in Protocols and Classes

The FxPlug SDK is made up of a number of protocols and classes. Some of these protocols are implemented by the host application and allow your plug-in access to functionality within that application. Other protocols are expected to be implemented by the application that contains your plug-in to allow the host application to communicate with your plug-in.

The following are the host-defined protocols:

Of the following protocols that your FxPlug plug-in can implement, you must implement either the FxFilter or FxGenerator protocol:

Color Representations

All colors are presented to the user in sRGB color space. The numerical values displayed in the inspector for color well parameters are the sRGB values for those colors. However, when a plug-in requests a color via one of the -[FxParameterRetrievalAPI getRedValue:greenValue:blueValue:::] methods, the values returned are in the processing space requested by the plug-in via the dictionary it returns from its -properties method.

In other words, if your plug-in sets the value of the kFxPropertyKey_DesiredProcessingColorInfo key to kFxImageColorInfo_RGB_LINEAR, the color wells return linear RGB colors. Likewise, if the value is set to kFxImageColorInfo_RGB_GAMMA_VIDEO, the color wells return gamma-correct (Rec. 709) RGB values.

The numerical values your plug-in receives are different from the values displayed to the user in the inspector, and this is by design.

FxTime Structure and Scheduling

The FxTime structure and scheduling APIs enable more accurate time representations and improve overall plug-in performance.

Frame Timing to Rational Timing

Previously, frames were represented using a double-precision floating point value. Now you use an FxTime data type:

typedef union {

    double  frame;

    CMTime* seconds;

} FxTime;

Notice that this new FxTime type is a union, which means time is represented as either a double-precision frame number or a pointer to a rational number of seconds. This maintains binary compatibility with existing plug-ins, because the size of a pointer and a double-precision frame number both happen to be 64 bits, they can fit in the same space, and it won’t change the size of any existing structures. This also allows currently shipping plug-ins to continue to use frame numbers to represent time.

The addition of the FxTime data type requires minor changes to any plug-ins built with the new SDK. This means you won’t be able to simply point to the new FxPlug framework and build your existing plug-ins. (However, plug-ins that are already shipping will run just fine.) If you decide to update or rebuild your plug-ins, you must change your code wherever you currently use a frame number (the renderInfo.frame field), and change it to use renderInfo.time (or in some cases renderInfo.time.frame). In most cases, if you have to make these changes, you should move away from using frame time and instead use rational time.

Scheduling APIs

The new scheduling API methods allow host applications to schedule the media contained in image wells. The -numberOfFramesToScheduleAtRenderTime method asks the plug-in how many frames it needs scheduled from a given image parameter. The -schedule method asks the plug-in to return the frame times needed from the image parameter for the given render time.

These new scheduling APIs were added as optional methods to the FxBaseEffect and FxFilter protocols. This means existing plug-ins will build without any changes. However, plug-ins that use the temporal image API or image well parameters should properly implement scheduling to take advantage of the performance improvements. The new FxBaseEffect methods have an additional parameter related to image parameter numbering.

Next Previous