FxPlug

Create custom effects plug-ins for Final Cut Pro X and Motion.

Overview

When the effect or look you want to achieve can't be created with the filters or generators provided with Final Cut Pro or Motion, use the FxPlug software development kit (SDK) to write your own custom visual effects. FxPlug is a compact, powerful image-processing plug-in architecture that lets you create unique, hardware-accelerated or CPU-based effects plug-ins with customized UI and onscreen controls.

FxPlug consists primarily of Objective-C protocol definitions. You create a plug-in by writing code in Objective-C, Objective-C++, or Swift that conforms to these protocols, implementing the methods declared by the protocols. The host application provides the capabilities in all the protocols that have the API suffix. Your plug-in is responsible for implementing the other protocols.

A screenshot of a frame in a Motion file depicting a filter called "Light Rays" applied to an image of a tower in an Italian town.

FxPlug 4 introduces fully “out-of-process” FxPlug plug-ins, which have no component that runs inside of the host application process. Out-of-process plug-ins provide improved security for end users and allow plug-in developers the freedom to choose from a variety of rendering technologies, such as OpenGL, Core Graphics, Core Image, or Metal to develop unique plug-ins that include on-screen controls and custom user interface elements—all running seamlessly in the host application. Plug-in developers can choose to implement in either Swift or Objective-C.

Additionally, the new FxTileableEffect API lets third-party plug-ins render only portions of the output (known as tiles) for more efficiency, in the same manner as Apple’s own plug-ins.

This documentation highlights new and updated concepts and APIs in FxPlug 4. You can find documentation for legacy plug-ins created with FxPlug 3 in the archived FxPlug 3.1.1 documentation.

Topics

Essentials

Setting Up for FxPlug Development

Download and install the required software to develop FxPlug plug-ins.

Using Out-of-Process FxPlug Plug-ins

Plug-in Fundamentals

Building an FxPlug Plug-in from an Xcode Template

Create a plug-in in Xcode with the FxPlug template.

Building an FxPlug Plug-in from Scratch

Create a plug-in in Xcode from scratch.

Using FxPlug APIs

Use various FxPlug APIs to communicate with host apps like Motion or Final Cut Pro X.

Editing Property Lists for FxPlug plug-ins

Modify the way hosts recognize and display your FxPlug plug-in with the Info.plist.

Rendering

Rendering in FxPlug

Use Metal or other frameworks to render images with your FxPlug plug-in.

Communicating with the Plug-in State

Prepare the necessary information, such as parameter values, for your FxPlug plug-in to render.

Working with Tiled Images

Render only the necessary tiles of an image in your FxPlug plug-in.

Optimizing FxPlug Plug-ins

Maintain consistent rendering at all resolutions and aspect ratios by using pixel transforms.

FxTileableEffect

The designated initializer for your plug-in for rendering only certain portions of the plug-in's output, referred to as tiles.

User Interface

Adding Parameters to Plug-ins

Create standard and custom user-facing parameters for your plug-in that will appear in the inspector.

Adding Onscreen Controls to Plug-ins

Simplify user interaction by using onscreen controls for your FxPlug plug-in.

FxPathAPI_v3

An API that defines the methods to retrieve information about paths, shapes, and masks the user has drawn on an object.

FxUndoAPI

An API that defines the methods implemented by the host application to allow a plug-in to manage the host application's undo queue.

3D and Lighting

Fx3DAPI_v4

An API that defines the methods the host application provides to get information about the 3D environment, including camera and object transforms.

FxLightingAPI_v3

An API for getting information about lights in a scene in a Motion project.

FxLightType

The lighting type.

FxMatrix44

The FxMatrix class encapsulates a 4x4 matrix object and provides matrix inversion and transforming of 2D and 3D points.

Color

Managing Color Space and Gamut in Plug-ins

Control the appearance of your rendering by using the color gamut API.

FxColorGamutAPI_v2

The FxColorGamutAPI allows your plug-in to query the host for the project's color gamut.

Time

Timing and Scheduling Media in Plug-ins

Use the scheduling APIs in FxPlug to retrieve frames from different times.

FxTimingAPI_v4

Defines the methods provided by the host to allow a plug-in to query the timing properties of its input image(s), image parameters, effect, timeline, and in/out points.

FxKeyframeAPI_v3

Defines the methods for manipulating keyframes of your plugin.

Testing and Deployment

Testing FxPlug Plug-ins

Test and debug FxPlug plug-ins using a variety of methods.

Preparing Plug-ins for Use in Final Cut Pro X

Add a plug-in to a Motion effect template so it can be used in Final Cut Pro.

Legacy Plug-ins

Migrating FxPlug 3 Plug-ins to FxPlug 4

Update existing FxPlug 3 plug-ins to out-of-process FxPlug 4 plug-ins.

FxVersioningAPI

The FxVersioningAPI protocol defines the methods a host application implements for identifying the version of the plug-in that was used by a project when the project was first created.

Legacy APIs

Older FxPlug 3 APIs