This is a guide to the basic machinery an OFX plugin uses to communicate with a host application, and goes into the fundamentals of the API.

An example plugin will be used to illustrate how all the machinery works, and its source can be found in the C++ file there. This plugin is a no-op image effect and does absolutely nothing to images, it is there purely to show you the basics of how a host and plugin work together. I’ll embed snippets of the plugin, but with some comments and debug code stripped for clarity.

An OFX plugin is a compiled dynamic library that an application can load on demand to add extra features to itself. A standardised API is used by a host and a plugin to communicate and do what is needed.

OFX has an underlying plugin mechanism that could be used to create a wide variety of plugin APIs, but currently only one has been layered on top of the base plugin machinery, which is the OFX Image Effect API.

The OFX API is specified using the C programming language purely by a set of header files, there are no libraries a plugin need to link against to make a plugin or host work. [1]

Key Concepts and Terminology

OFX has several key concepts and quite specific terminology, which definitely need defining.

  • a host is an application than can load OFX plugins and provides an environment for plugins to work in,

  • a plugin provides a set of extra features to a host application,

  • a binary is a dynamic library [2] that contains one or more plugins,

  • a suite is C struct containing a set of function pointers, which are named and versioned, Suites are the way a host allows a plugin to call functions within it and not have to link against anything,

  • a property is a named object of a restricted set of C types, which is accessed via a property suite,

  • a property set is a collection of properties,

  • an action is a call into a plugin to do something,

  • an API is a collection of suites, actions and properties that are used to do something useful, like process images. APIs are named and versioned.

The Two Bootstrapper Functions

To tell the host what it has inside it, a plugin binary needs to expose two functions to bootstrap the whole host/plugin communications process. These are:

  • OfxGetNumberOfPlugins() A function that returns the number of plugins within that binary

  • OfxGetPlugin() A function that returns a struct that provides the information required by a host to bootstrap the plugin.

The host should load the binary using the appropriate operating system calls, then search it for these two exposed symbols. It should then iterate over the number of advertised plugins and decide what to do with the plugins it finds.

It should go without saying that a host should not hang onto the pointer returned by OfxGetPlugin() after it unloads a binary, as the data will not be valid. It should also copy any strings out of the struct if it wants to keep them.

From our example, we have the following…

basics.cpp

// how many plugins do we have in this binary?
int OfxGetNumberOfPlugins(void)
{
  return 1;
}

// return the OfxPlugin struct for the nth plugin
OfxPlugin * OfxGetPlugin(int nth)
{
  if(nth == 0)
    return &effectPluginStruct;
  return 0;
}

The OfxPluginStruct

The OfxPlugin returned by OfxGetPlugin() provides information about the implementation of a particular plugin.

The fields in the struct give the host enough information to uniquely identify the plugin, what it does, and what version it is. These are:

  • pluginAPI - the name of the API that this plugin satisfies,

    image effect plugins should set this to kOfxImageEffectPluginApi,

  • apiVersion - the version of that API the plug-in was written to

  • pluginIdentifier - the unique name of the plug-in. Used only to disambiguate the plug-in from all other plug-ins, not necessarily for human eyes

  • pluginVersionMajor - the major version of the plug-in, typically incremented when compatibility breaks,

  • pluginVersionMinor - the minor version of the plug-in, typically incremented when bugs and so on are fixed,

  • setHost - a function used to set the OfxHost struct in the plugin,

  • mainEntry - the function a host will use to send action requests to the plugin.

Our example plugin’s OfxPlugin struct looks like…

basics.cpp

static OfxPlugin effectPluginStruct =
{
  kOfxImageEffectPluginApi,
  1,
  "org.openeffects:BasicsExamplePlugin",
  1,
  0,
  SetHostFunc,
  MainEntryPoint
};

Using this information a host application can grab a plugin struct then figure out if it supports the API at the given version.

The pluginIdentifier is not meant to be the presented to the user, it is a purely a unique id for that plugin, and any related versions of that plugin. Use this for serialisation etc… to identify the plugin. The domainname:pluginname nomenclature is suggested best practice for a unique id. For a user visible name, use the kOfxPropVersionLabel property

Plugin versioning allows a plugin (as identified by the pluginIdentifier field) to be updated and redistributed multiple times, with the host knowing which is the most appropriate version to use. It even allows old and new versions of the same plugin to be used simultaneously within a host application. There are more details on how to use the version numbers in the OFX Programming Reference.

The setHost function is used by the host to give the plugin an OfxHost struct (see below), which is the bit that gives the plugin access to functions within the host application.

Finally the mainEntry is the function called by the host to get the plugin to carry out actions. Via the property system it behaves as a generic function call, allowing arbitrary numbers of parameters to be passed to the plugin.

Suites

A suite is simply a struct with a set of function pointers. Each suite is defined by a C struct definition in an OFX header file, as well a C literal string that names the suite. A host will pass a set of suites to a plugin, each suite having the set of function pointers filled appropriately.

For example, look in the file ofxMemory.h for the suite used to perform memory allocation:

ofxMemory.h

Notice also, the version number built into the name of the memory suite. If we ever needed to change the memory suite for some reason, OfxMemorySuiteV2 would be defined, with a new set of function pointers. The new suite could then live along side the old suite to provide backwards compatibility.

Plugins have to ask for suites from the host by name with a specific version, how we do that is covered next.

The OfxHost and Fetching Suites

An instance of an OfxHost C struct is the thing that allows a plugin to get suites and provides information about a host application

A plugin is given one of these by the host application via the OfxPlugin::setHost() function it previously passed to the host.

There are two members to an OfxHost, the first is a property set (more on properties in a moment) which describes what the host does and how it behaves.

The second member is a function used to fetch suites from the host application. Going back to our example plugin, we have the following bits of code. For the moment ignore how and when the LoadAction is called, but notice what it does…

basics.cpp

//  The anonymous namespace is used to hide symbols from export.
namespace {
  OfxHost               *gHost;
  OfxPropertySuiteV1    *gPropertySuite = 0;
  OfxImageEffectSuiteV1 *gImageEffectSuite = 0;

  ////////////////////////////////////////////////////////////////////////////////
  /// call back passed to the host in the OfxPlugin struct to set our host pointer
  void SetHostFunc(OfxHost *hostStruct)
  {
    gHost = hostStruct;
  }

  ////////////////////////////////////////////////////////////////////////////////
  /// the first action called
  OfxStatus LoadAction(void)
  {
    gPropertySuite    = (OfxPropertySuiteV1 *) gHost->fetchSuite(gHost->host,
                                                                 kOfxPropertySuite,
                                                                 1);
    gImageEffectSuite = (OfxImageEffectSuiteV1 *) gHost->fetchSuite(gHost->host,
                                                                    kOfxImageEffectSuite,
                                                                    1);

    return kOfxStatOK;
  }

}

Notice that it is fetching two suites by name from the host. Firstly the all important kOfxPropertySuite and then the kOfxImageEffectSuite. It squirrels these away for later use in two global pointers. The plugin can then use the functions in the suites as and when needed.

Properties

The main way plugins and hosts communicate is via the properties mechanism. A property is a named object inside a property set, which is a bit like a python dictionary. You use the property suite, defined in the header ofxProperty.h to access them.

Properties can be of the following fundamental types…

  • int

  • double

  • char *

  • void *

So for in our example we have….

basics.cpp

OfxPropertySetHandle effectProps;
gImageEffectSuite->getPropertySet(effect, &effectProps);

gPropertySuite->propSetString(effectProps, kOfxPropLabel, 0, "OFX Basics Example");

Here the plugin is using the effect suite to get the property set on the effect. It is then setting the string property kOfxPropLabel to be “OFX Basics Example”. There are corresponding calls for the other data types, and equivalent set calls. All pretty straight forwards.

Notice the 0 passed as the third argument, which is an index. Properties can be multidimensional, for example the current pen position in a graphics viewport is a 2D integer property. You can get and set individual elements in a multidimensional property or you could use calls like OfxPropertySuiteV1::propSetIntN to set all values at once. Of course there exists N calls for all types, as well as corresponding setting calls.

The various OFX header files are littered with C macros that define the properties used by the API, what type they are, what property set they are on and whether you can read and/or write them. The OFX reference guide had all the properties listed by name and object they are on, as well as what they are for.

By passing information via property sets, rather than fixed C structs, you gain a flexibility that allows for simple incremental additions to the API without breaking backwards compatibility and builds. It does come at a cost (being continual string look-up), but the flexibility it gives is worth it.

Note

Plugins have to be very careful with scope of the pointer returned when you fetch a string property. The pointer will be guaranteed to be valid only until the next call to an OFX suite function or until the action ends. If you want to use the string out of those scope you must copy it.

Actions

Actions are how a host tells a plugin what to do. The mainEntry function pointer in the OfxPlugin structure is the what accepts actions to do whatever is being requested.

Where:

  • action is a C string that specifies what is to be done by the plugin, e.g. OfxImageEffectActionRender tells an image effect plugin to render a frame

  • handle is the thing that is being operated on, and needs to be downcast appropriately, what this is will depend on the action

  • inArgs is a well defined property set that are the arguments to the action

  • outArgs is a well defined property set where a plugin can return values as needed.

The entry point will return an OfxStatus to tell the host what happened. A plugin is not obliged to trap all actions, just a certain subset, and if it doesn’t need to trap the action, it can just return the status kOfxStatReplyDefault to have the host carry out the well defined default for that action.

So looking at our example we can see its main entry point:

basics.cpp

OfxStatus MainEntryPoint(const char *action,
                         const void *handle,
                         OfxPropertySetHandle inArgs,
                         OfxPropertySetHandle outArgs)
{
  // cast to appropriate type
  OfxImageEffectHandle effect = (OfxImageEffectHandle) handle;

  OfxStatus returnStatus = kOfxStatReplyDefault;

  if(strcmp(action, kOfxActionLoad) == 0) {
    returnStatus = LoadAction();
  }
  else if(strcmp(action, kOfxActionUnload) == 0) {
    returnStatus = UnloadAction();
  }
  else if(strcmp(action, kOfxActionDescribe) == 0) {
    returnStatus = DescribeAction(effect);
  }
  else if(strcmp(action, kOfxImageEffectActionDescribeInContext) == 0) {
    returnStatus = DescribeInContextAction(effect, inArgs);
  }
  else if(strcmp(action, kOfxActionCreateInstance) == 0) {
    returnStatus = CreateInstanceAction(effect);
  }
  else if(strcmp(action, kOfxActionDestroyInstance) == 0) {
    returnStatus = DestroyInstanceAction(effect);
  }
  else if(strcmp(action, kOfxImageEffectActionIsIdentity) == 0) {
    returnStatus = IsIdentityAction(effect, inArgs, outArgs);
  }

  return returnStatus;
}

You can see the plugin is trapping seven actions and is saying to do the default for the rest of the actions.

In fact only four actions need to be trapped for an image effect plugin [3], but our machinery plugin is trapping more for illustrative purposes.

What is on the property sets, and what the handle is depends on the action being called. Some actions have no arguments (eg: the kOfxLoadAction), while others have in and out arguments, e.g. the kOfxImageEffectActionIsIdentity.

Actions give us a very flexible and expandable generic function calling mechanism. This means it is trivial to expand the API via adding extra properties or actions to the API without impacting existing plugins or applications.

Note

For the main entry point on image effect plugins, the handle passed in will either be NULL or an OfxImageEffectHandle, which is just a blind pointer to host specific data that represents the plugin.

Basic Actions For Image Effect Plugins

There are a set of actions called on a plugin that signal to the plugin what is going on and to get it to tell the host what the plugin does. These need to be called in a specific sequence to make it all work properly.

The Load and Unload Actions

The kOfxActionLoad is the very first action passed to a plugin. It will be called after the setHost callback has been used to pass the OfxHost to the plugin. It is the point at which a plugin gets to create global structures that it will later be used across all instances. From our load action snippet above, you can see that the plugin is fetching two suites and caching the pointers away for later use.

At some point the host application will want to unload the binary that the plugin is contained in, either when the host quits or the plugin is no longer needed by the host application. The host needs to notify the plugin of this, as it may need to perform some clean up. The kOfxActionUnload action is sent to the plugin by the host to warn the plugin of it’s imminent demise. After this action is called the host can no longer issue any actions to that plugin unless another kOfxActionLoad action is called. In our example plugin, the unload does nothing.

Note

Hosts should always pair the kOfxActionLoad with a kOfxActionUnload, otherwise all sorts of badness can happen, including memory leaks, failing license checks and more. There is one exception to this, which is if a plugin encounters an error during the load action and returns an error state. In this case only, the plugin must clean up before it returns, and , the balancing unload action is not called. In all other circumstances where an error is returned by a plugin from any other action, the unload action will eventually be called.

Describing Plugins To A Host

Once a plugin has had kOfxActionLoad called on it, it will be asked to describe itself. This is done with the kOfxActionDescribe action. From our example plugin, here is the function called by our main entry point in response to the describe action.

basics.cpp

OfxStatus DescribeAction(OfxImageEffectHandle descriptor)
{
  // get the property set handle for the plugin
  OfxPropertySetHandle effectProps;
  gImageEffectSuite->getPropertySet(descriptor, &effectProps);

  // set some labels and the group it belongs to
  gPropertySuite->propSetString(effectProps,
                                kOfxPropLabel,
                                0,
                                "OFX Basics Example");
  gPropertySuite->propSetString(effectProps,
                                kOfxImageEffectPluginPropGrouping,
                                0,
                                "OFX Example");

  // define the image effects contexts we can be used in, in this case a simple filter
  gPropertySuite->propSetString(effectProps,
                                kOfxImageEffectPropSupportedContexts,
                                0,
                                kOfxImageEffectContextFilter);

  return kOfxStatOK;
}

You will see that it fetches a property set (via the image effect suite) and sets various properties on it. Specifically the label used in any user interface to name the plugin, and the group of plugins it belongs to. The grouping name allows a developer to ask the host to arrange all plugins with that group name into a single menu/container in the user interface.

The final thing it sets is the single context it can be used in. Contexts are specific to image effect plugins, and they are there because a plugin can be used in many different ways. We call each way an image effect plugin can be used a context. In our example we are saying our plugin can behave as a filter only. A filter is simply an effect with one and only one input clip and one mandated output clip. This is typical of systems such as editors which can drop effects directly onto a clip in a time-line. For more complex systems, e.g. a node graph compositor, you might want to allow the same plugin to have more input clips and a richer parameter set, which we call the general context. A plugin can work one or more contexts, not all of which need be supported by a host.

Because it can be used in different contexts, and will need to be described differently in each, an image effect plugin has a two tier description process. First kOfxActionDescribe is called to set attributes common to all the contexts the plugin can be used in, then the kOfxImageEffectActionDescribeInContext action is called, once for each context that the host wants to use the effect in.

Again from our example plugin, here is how it responds to the describe in context action…

Note

A plugin developer might package multiple plugins in a single binary and another multiple plugins into multiple binaries yet both expect them to show up in the same plugin group [4] in the user interface.

basics.cpp

OfxStatus
DescribeInContextAction(OfxImageEffectHandle descriptor, OfxPropertySetHandle inArgs)
{
  // check state
  ERROR_ABORT_IF(gDescribeCalled == false, "DescribeInContextAction called before DescribeAction");
  gDescribeInContextCalled = true;

  // get the context from the inArgs handle
  char *context;
  gPropertySuite->propGetString(inArgs, kOfxImageEffectPropContext, 0, &context);

  ERROR_IF(strcmp(context, kOfxImageEffectContextFilter) != 0, "DescribeInContextAction called on unsupported contex %s", context);

  OfxPropertySetHandle props;
  // define the mandated single output clip
  gImageEffectSuite->clipDefine(descriptor, "Output", &props);

  // set the component types we can handle on out output
  gPropertySuite->propSetString(props, kOfxImageEffectPropSupportedComponents, 0, kOfxImageComponentRGBA);
  gPropertySuite->propSetString(props, kOfxImageEffectPropSupportedComponents, 1, kOfxImageComponentAlpha);

  // define the mandated single source clip
  gImageEffectSuite->clipDefine(descriptor, "Source", &props);

  // set the component types we can handle on our main input
  gPropertySuite->propSetString(props, kOfxImageEffectPropSupportedComponents, 0, kOfxImageComponentRGBA);
  gPropertySuite->propSetString(props, kOfxImageEffectPropSupportedComponents, 1, kOfxImageComponentAlpha);

  return kOfxStatOK;
}

In this case I’ve left the error check cluttering up the snippet so you can see how the inArgs property set is used to specify which context is currently being described. Our example then goes on define two image clips, the first used for output, and the second used for input. The API docs specify that a filter effect needs to specify both of these with exactly those names. Not also how the effect is setting a multidimensional property associated with each clip to specify what pixel types it supports on those clips.

For more complex effects, these actions are the point where you specify parameters that the effect wants to use, and get to tweak a whole range of settings to say how the plugin behaves.

Creating Instances

So far a host knows what our plugin looks like and how it should behave, but it isn’t using it to process pixels yet. At some point a user will click on a button in a UI and to say they want to use the plugin. To do that a host creates an instance of the plugin. An instance represents a unique copy of the plugin and contains all the state needed for that. For example, a blur plugin may be instantiated many times in a compositing graph, each instance will have parameters set to a different value, and be connected to different input and output clips.

A plugin developer may need to attach data to each plugin instance, typically to tie the plugin into their own image processing infrastructure. They get the chance to do that via the kOfxActionCreateInstance action. The host will call that action just after they have created and initialised their host-side data structures that represent the plugin. Our example plugin doesn’t actually do anything on create instance, but it could choose to attached it’s own data structures to the instance via the kOfxPropInstanceData property.

A plugin will also want to destroy any of its own data structures when an instance is destroyed. It gets to do that in the kOfxActionDestroyInstance action.

Our example plugin exercises both of those action just to illustrate what is going it. It simply places a string into the instance data property which it later fetches and destroys. In real plugins, this is typically a hook to deeper plugin side data structures.

Note

Because a host might have asynchronous UI handling and multiple render threads on the same instance, it is suggested that a plugin that wants to write to the instance data after instance creation do so in a safe manner (e.g. by semaphore lock).

basics.cpp

OfxStatus CreateInstanceAction(OfxImageEffectHandle instance)
{
  OfxPropertySetHandle effectProps;
  gImageEffectSuite->getPropertySet(instance, &effectProps);

  // attach some instance data to the effect handle, it can be anything
  char *myString = strdup("This is random instance data that could be anything you want.");

  // set my private instance data
  gPropertySuite->propSetPointer(effectProps,
                                 kOfxPropInstanceData,
                                 0,
                                 (void *) myString);

  return kOfxStatOK;
}

// instance destruction
OfxStatus DestroyInstanceAction(OfxImageEffectHandle instance)
{
  OfxPropertySetHandle effectProps;
  gImageEffectSuite->getPropertySet(instance, &effectProps);

  // get my private instance data
  char *myString = NULL;
  gPropertySuite->propGetPointer(effectProps,
                                 kOfxPropInstanceData,
                                 0,
                                 (void **) &myString);
  ERROR_ABORT_IF(myString == NULL, "Instance data should not be null!");
  free(myString);

  return kOfxStatOK;
}

Note

kOfxActionDestroyInstance should always be called when an instance is destroyed, and furthermore all instances need to have had kOfxActionDestroyInstance called on them before kOfxActionUnload can be called.

What About The Image Processing?

This plugin is pretty much a hello world OFX example, it doesn’t actually process any images. Normally a host application would call the kOfxImageEffectActionRender action when it wants the plugin to render a frame. Our simple plugin gets around processing any images by trapping the kOfxImageEffectActionIsIdentity action. This action lets the plugin tell the host application that it currently does nothing to its inputs, for example a blur effect with the blur size of zero. In such a case the host can simply ignore the plugin and use its source images directly. And here is the code that does that:

basics.cpp

OfxStatus IsIdentityAction( OfxImageEffectHandle instance,
                            OfxPropertySetHandle inArgs,
                            OfxPropertySetHandle outArgs)
{
  // we set the name of the input clip to pull data from
  gPropertySuite->propSetString(outArgs, kOfxPropName, 0, "Source");
  return kOfxStatOK;
}

The plugin is telling the host to pass through an unprocessed image from an input clip, and because plugins can have more than one input it needs to tell the host which clip to use. It does that by setting the kOfxPropName property on the outargs. It also returns kOfxStatOK to indicate that it has trapped the action and that the plugin is currently doing nothing.

Remember we said that each action has a well defined set of in and out arguments? In the case of the is identity action these are…

A proper plugin would examine the inArgs, its parameters and see if it is doing anything to its inputs. If it does need to process images it would return kOfxStatReplyDefault rather than kOfxStatOK.

Life Cycle of a Plugin

Now we’ve outlined the basic actions and functions in a plugin, we should clearly specify the calling sequence. Failure to call them in the right sequence will lead to all sorts of undefined behaviour.

Assuming the host has done nothing apart from load the dynamic library that contains plugins and has found the two boostrapping symbols in the plugin, the host should then…

  • call OfxGetNumberOfPlugins to discover the number of plugins

  • call OfxGetPlugin for each of the N plugins in the binary and decide if it can use them or not (by looking at APIs and versions)

At this point the code in the binary should have done nothing apart from run those two functions. The host is free to unload the binary at this point without further interaction with the plugin.

If the host decides it wants to use one of the plugins in the binary it must then…

If the host wants to actually use a plugin, it creates whatever host side data structures are needed then…

When a host wants to get rid of an instance, before it destroys any of it’s own data structures it calls kOfxActionDestroyInstance

When the host wants to be done with the plugin, and before it dynamically unloads the binary it calls kOfxActionUnload, all instances must have been destroyed before this call.

Once the final kOfxActionUnload has been called, even if it doesn’t dynamically unload the binary, the host can no longer call the main entry point on that specific plugin until it once more calls kOfxActionLoad.

Packaging A Plugin

The compiled code for a plugin is contained in a dynamic library. Plugins are distributed as a directory structure that allows you to add icons and other resources you may need. There is more detailed information in the OFX Programming Reference Guide.

Summary

This example has shown you the basics of the OFX plugin machinery, the main things it illustrated was…

  • the two bootstrapper functions exposed by a plugin that start the plugin discovery process,

  • the main entry point of a plugin is given actions by the host application to do things,

  • the plugin gets suites from the host to gain access to functions in the host,

  • property sets are the main way of passing data back and forth across the API,

  • image effect plugins are described in a two step process,

  • instances are created when a host wants to use a plugin to do something

  • actions must be called in a certain order for the API to work cleanly.