This chapter provides a brief overview of the basic plug-in architecture and some of the reasoning behind it. It will touch lightly .

The OFX API is specified using the 'C' programming language. The traditional languages used to implement visual effects applications and plug-ins have been C and C++, so we stuck with that school. By making the API C, rather than C++, you remove the whole set of problems around C++ symbol mangling between the host an application.

The APIs defined by OFX are defined purely by a set of C header files and the associated documentation. There are no binary libraries to link against.

The host relies on two symbols within a plug-in, all other communication is boot strapped from those two symbols. The plug-in has no symbolic dependancies from the host. This minimal symbolic dependancy allows for run-time determination of what features to provide over the API, making implementation much more flexible and less prone to backwards compatibility problems.

A host communicates with a plug-in via a

A host communicates with a plug-in via a

This chapter will describe in detail a fully functioning, but simple OFX image effect plug-in that inverts 8 bit RGBA images. It gives a flavour for how the API operates and some of the components in it. The source will be broken down into sections and each one explained as we go along. The code is actually C++, but it uses the raw OFX API. The code is not meant to be perfectly optimised example of how to write an image processing effect, but rather as an illustrative example of the API.

 #include <string.h> #include "ofxCore.h" #include "ofxProperty.h" #include "ofxImageEffect.h"

This section of code shows the headers used by the invert plug-in. It includes three OFX header files (you can tell because they start with "ofx") which are...

The system include file string.h is for use of strcmp as the API passes strings about rather than integers or enums to specify actions and properties.

// forward declaration of two functions needed by the plug-in struct
static OfxStatus pluginMain(const char *action,  const void *handle, OfxPropertySetHandle inArgs,  OfxPropertySetHandle outArgs);
static void setHostFunc(OfxHost *hostStruct);

////////////////////////////////////////////////////////////////////////////////
// the plugin struct 
static OfxPlugin pluginStruct = 
{       
  kOfxImageEffectPluginApi,
  1,
  "net.sf.openfx.OfxInvertExample",
  1,
  0,
  setHostFunc,
  pluginMain
};
   
// the mandated function to return the nth plug-in
OfxExport OfxPlugin *
OfxGetPlugin(int nth)
{
  if(nth == 0)
    return &pluginStruct;
  return 0;
}
 
// the mandated function to return the number of plug-ins in this binary
OfxExport int
OfxGetNumberOfPlugins(void)
{       
  return 1;
}

The first thing to note in this section are the two functions OfxGetPlugin and OfxGetNumberOfPlugins. These two functions are the only symbols that a plug-in must export and are there to boot strap the whole plug-in identification and definition process. Note the macro OfxExport, which should be inserted before any symbol that needs to be exported from the plug-in.

OfxGetNumberOfPlugins is the first function by a host after a binary is loaded. It returns the number of separate plug-ins contained inside the binary. In this case we have only one plug-in.

OfxGetPlugin is called once for each plug-in inside the binary, and returns an OfxPlugin struct. This struct is used to tell the host what kind of plug-in it is, it's name, versioning info and to give the host two functions to use for communications. Our function returns a pointer to the static pluginStruct. All such structs should be static to avoid memory allocation issues, otherwise they will not be deleted by the host.

In order the members of pluginStruct tell the host...

// pointer to the host structure passed to us by the host application
OfxHost   *gHost;

// function called by the host application to set the host structure
static void
setHostFunc(OfxHost *hostStruct)
{
  gHost = hostStruct;
}

This section has the structure that holds information about the host application and allows us to fetch suites from the host. The setHostFunc is called by the host application to set this pointer and is passed to the host inside the OfxPlugin struct.

 // forward declarations static OfxStatus render(OfxImageEffectHandle  instance, OfxPropertySetHandle inArgs, OfxPropertySetHandle outArgs); static OfxStatus describe(OfxImageEffectHandle effect); static OfxStatus onLoad(void); static OfxStatus describeInContext( OfxImageEffectHandle  effect,  OfxPropertySetHandle inArgs)  // The main entry point function static OfxStatus pluginMain(const char *action,  const void *handle, OfxPropertySetHandle inArgs,  OfxPropertySetHandle outArgs) {   // cast to appropriate type   OfxImageEffectHandle effect = (OfxImageEffectHandle) handle;    // called as the very first action before any other   if(strcmp(action, kOfxActionLoad) == 0) {     return onLoad();   }   // called to describe the plug-in   else if(strcmp(action, kOfxActionDescribe) == 0) {     return describe(effect);   }   // called to describe the plug-in in a given context   else if(strcmp(action, kOfxImageEffectActionDescribeInContext) == 0) {     return describeInContext(effect, inArgs);   }   // called to render a frame   else if(strcmp(action, kOfxImageEffectActionRender) == 0) {     return render(effect, inArgs, outArgs);   }            // all other actions return the default value   return kOfxStatReplyDefault; } 

The pluginMain was passed to the host int the OfxPlugin struct returned by OfxGetPlugin. This function is where the host tells the plug-in what it needs to do. You will note that the actions passed to the plug-in are encoded as strings. This makes actions easily extensible whilst minimising the chances of name clashing.

The function also takes a "handle" argument. This handle is the thing the action must be performed on. In this case, as we are an image effect, the handle must be cast to an OfxImageEffectHandle, which is simply a blind pointer to some host data representing an image effect.

The last two parameters inArgs and outArgs are used to pass in arguments for the specific action. These are encapsulated via blind property sets. The inArgs are extra arguments the action will need to do its job, whilst outArgs are for things the plug-in will need to set to do its action.

Our main entry only traps four of the many possible actions. The actual actions will be described below.

 OfxImageEffectSuiteV1 *gEffectSuite = 0; OfxPropertySuiteV1    *gPropertySuite = 0;  //////////////////////////////////////////////////////////////////////////////// // Called at load static OfxStatus onLoad(void) {     // fetch the host suites out of the global host pointer     if(!gHost) return kOfxStatErrMissingHostFeature;          gEffectSuite     = (OfxImageEffectSuiteV1 *) gHost->fetchSuite(gHost->host, kOfxImageEffectSuite, 1);     gPropertySuite   = (OfxPropertySuiteV1 *)    gHost->fetchSuite(gHost->host, kOfxPropertySuite, 1);     if(!gEffectSuite || !gPropertySuite)         return kOfxStatErrMissingHostFeature;     return kOfxStatOK; } 

The load action is always the first action called after the initial boot-strap phase has happened. By this time the plug-in's setHost function will have been called, so we have access to the host pointer and so the ability to fetch suites.

What this action does is first to check that the host application has in fact set the gHost pointer, it then goes ahead and fetches two suites from the host. These suites are simply structs full of function pointers from the host which the plug-in uses to communicate with the host. We are only fetching two suites from the host, the OfxImageEffectSuiteV1 to give us access to images and more, and the OfxPropertySuiteV1 which allows us to access values in property sets.

// the plug-in's description routine
static OfxStatus
describe(OfxImageEffectHandle effect)
{
  // get the property handle for the plugin
  OfxPropertySetHandle effectProps;
  gEffectSuite->getPropertySet(effect, &effectProps);

  // say we cannot support multiple pixel depths and let the clip preferences action deal with it all.
  gPropertySuite->propSetInt(effectProps, kOfxImageEffectPropSupportsMultipleClipDepths, 0, 0);
  
  // set the bit depths the plug-in can handle
  gPropertySuite->propSetString(effectProps, kOfxImageEffectPropSupportedPixelDepths, 0, kOfxBitDepthByte);

  // set plug-in label and the group it belongs to
  gPropertySuite->propSetString(effectProps, kOfxPropLabel, 0, "OFX Invert Example");
  gPropertySuite->propSetString(effectProps, kOfxImageEffectPluginPropGrouping, 0, "OFX Example");

  // define the contexts we can be used in
  gPropertySuite->propSetString(effectProps, kOfxImageEffectPropSupportedContexts, 0, kOfxImageEffectContextFilter);
  
  return kOfxStatOK;
}

The purpose of the describe action is to tell the host the overall behaviour of the plug-in. The OfxImageEffectHandle passed to the describe action is a descriptor as opposed to an instance. A descriptor is a handle that is used to tell the host how a plug-in should look, whilst an instance is an actual running copy of a plug-in. Descriptors are passed to only two actions, the describe action, and the describe in context action. Most other actions that are passed an instance handle.

The first thing this function does is to fetch the handle holding the properties used to describe the plug-in. Note how it uses the gEffectSuite pointer to do this.

The next thing the plug-in does is set the integer property kOfxImageEffectPropSupportsMultipleClipDepths to be false using the property suite. This tells the host application that the plug-in can only support a single pixel depth at a time, otherwise the host might attempt to have an 8 bit input and a 16 bit output.

Note how the property setting functions take four arguments. The first is the set of properties to be modified, the second is the name (again a string) of the property in that set they wish to change, the third is the index of the property (as properties can be multi-dimensional) and the last is the value they wish to set.

The plug-in goes on to set properties that describe it as supporting only images of 8 bits per component, the user visible name of the effect, the grouping the effect should be placed in on any user interface and finally the context it can be used under.

An image effect context describes the semantics of how a plug-in should be used. In this case we are saying the plug-in is a filter, which means it has to have one input clip called "Source" and one output clip called "Output". Other contexts include transitions, where an image effect has two inputs and a single output and is require to go from one to the other, a general context for tree based compositing systems and several more. A plug-in can say that it works in more than one context, which brings us on to the next function.

 //  describe the plug-in in context static OfxStatus describeInContext( OfxImageEffectHandle  effect,  OfxPropertySetHandle inArgs) {   OfxPropertySetHandle props;   // define the single output clip in both contexts   gEffectSuite->clipDefine(effect, "Output", &props);    // set the component types we can handle on out output   gPropertySuite->propSetString(props, kOfxImageEffectPropSupportedComponents, 0, kOfxImageComponentRGBA);    // define the single source clip in both contexts   gEffectSuite->clipDefine(effect, "Source", &props);    // set the component types we can handle on our main input   gPropertySuite->propSetString(props, kOfxImageEffectPropSupportedComponents, 0, kOfxImageComponentRGBA);    return kOfxStatOK; } 

The describe in context action is called once for each context that a plug-in says it can work in. Here the plug-in must define the clips it will use and any parameters it may need for that context. The set of clips and parameters need not be the same for each context, though typically a core of parameters and some clips will be the same. Note that, as with the describe action, the describe in context action is passed a descriptor rather than an instance.

The first thing our function does is to define the clip called "Output" which is mandatory for the filter context. This function returns a property set which is used to describe how the effect wants to deal with that clip. In this case the effect says that it will only accept RGBA images on the output. Next it does the same for the mandated "Source" clip. Having defined the two clips needed for this context it returns.

// look up a pixel in the image, does bounds checking to see if it is in the image rectangle
inline OfxRGBAColourB *
pixelAddress(OfxRGBAColourB *img, OfxRectI rect, int x, int y, int bytesPerLine)
{  
  if(x < rect.x1 || x >= rect.x2 || y < rect.y1 || y > rect.y2)
    return 0;
  OfxRGBAColourB *pix = (OfxRGBAColourB *) (((char *) img) + (y - rect.y1) * bytesPerLine);
  pix += x - rect.x1;  
  return pix;
}

// the process code  that the host sees
static OfxStatus render(OfxImageEffectHandle  instance,
                        OfxPropertySetHandle inArgs,
                        OfxPropertySetHandle outArgs)
{
    // get the render window and the time from the inArgs
    OfxTime time;
    OfxRectI renderWindow;
  
    gPropertySuite->propGetDouble(inArgs, kOfxPropTime, 0, &time);
    gPropertySuite->propGetIntN(inArgs, kOfxImageEffectPropRenderWindow, 4, &renderWindow.x1);

    // fetch output clip
    OfxImageClipHandle outputClip;
    gEffectSuite->clipGetHandle(instance, "Output", &outputClip, 0);

    // fetch image to render into from that clip
    OfxPropertySetHandle outputImg;
    gEffectSuite->clipGetImage(outputClip, time, NULL, &outputImg);

    // fetch output image info from that handle
    int dstRowBytes, dstBitDepth;
    OfxRectI dstRect;
    void *dstPtr;
    gPropertySuite->propGetInt(outputImg, kOfxImagePropRowBytes, 0, &dstRowBytes);
    gPropertySuite->propGetIntN(outputImg, kOfxImagePropBounds, 4, &dstRect.x1);
    gPropertySuite->propGetPointer(outputImg, kOfxImagePropData, 0, &dstPtr);
  
    // fetch main input clip
    OfxImageClipHandle sourceClip;
    gEffectSuite->clipGetHandle(instance, "Source", &sourceClip, 0);

    // fetch image at render time from that clip
    OfxPropertySetHandle sourceImg;
    gEffectSuite->clipGetImage(sourceClip, time, NULL, &sourceImg);

    // fetch image info out of that handle
    int srcRowBytes, srcBitDepth;
    OfxRectI srcRect;
    void *srcPtr;
    gPropertySuite->propGetInt(sourceImg, kOfxImagePropRowBytes, 0, &srcRowBytes);
    gPropertySuite->propGetIntN(sourceImg, kOfxImagePropBounds, 4, &srcRect.x1);
    gPropertySuite->propGetPointer(sourceImg, kOfxImagePropData, 0, &srcPtr);

    // cast data pointers to 8 bit RGBA
    OfxRGBAColourB *src = (OfxRGBAColourB *) srcPtr;
    OfxRGBAColourB *dst = (OfxRGBAColourB *) dstPtr;

    // and do some inverting
    for(int y = renderWindow.y1; y < renderWindow.y2; y++) {
        if(gEffectSuite->abort(instance)) break;

        OfxRGBAColourB *dstPix = pixelAddress(dst, dstRect, renderWindow.x1, y, dstRowBytes);

        for(int x = renderWindow.x1; x < renderWindow.x2; x++) {
        
            OfxRGBAColourB *srcPix = pixelAddress(src, srcRect, x, y, srcRowBytes);

            if(srcPix) {
                dstPix->r = 255 - srcPix->r;
                dstPix->g = 255 - srcPix->g;
                dstPix->b = 255 - srcPix->b;
                dstPix->a = 255 - srcPix->a;
            }
            else {
                dstPix->r = 0;
                dstPix->g = 0;
                dstPix->b = 0;
                dstPix->a = 0;
            }
            dstPix++;
        }
    }

    // we are finished with the source images so release them
    gEffectSuite->clipReleaseImage(sourceImg);
    gEffectSuite->clipReleaseImage(outputImg);
  
    // if we aborted, then we have failed to produce and image, so say so
    if(gEffectSuite->abort(instance)) return kOfxStatFailed;

    // otherwise all was well
    return kOfxStatOK;
}

The render action is where a plug-in turns its input images into output images. The first thing to note is that the effect is no longer a descriptor by an. For our simple example, this makes not much difference, however if the plug-in is maintaining private data, it is very important.

The first thing the render function does is to extract two properties from the inArgs property set. These are the time to render at, and the window to render over. Note that the render window is a 4 dimensional integer property.

Next the function fetches the output clip. A clip is a handle that is accessible by name and represents a sequences of images. The returned handle is valid for the lifetime of the instance, and so does not need releasing or deleting. Next an image is extracted from the clip. An image, unlike a clip, does need to be released when the plug-in is done with it.

Images are encapsulated as a property set, and so the ordinary property mechanism is used to fetch out information from the image. In this case three properties are needed, the rowBytes, or the number of bytes in a scan line (as there may be padding at the end), the image bounds, being the region where there is image data and a pointer to the image data. The source image is fetched in a similar way as the destination image.

Next the void * data pointers are cast to OfxRGBAColourB pointers, and we start iterating over the render window filling in output pixels. The render window must always be equal to or less than the bounds on the destination image. The inline function pixelAddress shows how pixel arithmetic is performed. Note the abort function from the image effect suite being called at every scan line to see if the rendering should be halted.

Finally, once we are done, the images are released and we return.

Our small working example shows the core mechanisms behind the OFX Image Effect API, but leaves out much of the messy detail. The important things to note are the use of suites to call functions on the host, the use of properties to get and set values in objects and the use of actions to call things on the plug-in.

There are many more suites which have not been used, as well as actions that have not been trapped, as well as gory bits to do with pixel aspect ratios, interlacing and more. These extra suites and actions add a rich functionality to OFX that give it a great flexibility as well as dealing with the evil little details such as video standards.

As explained in the introduction, OFX is actually several things,

This chapter concentrates on defining the underlying architecture, including how plug-ins should be identified, defined, versioned, installed and the initial bootstrapping of communication occurs.

The two OFX include files relevant for this section are

OFX APIs are all implemented via prototyped "C" header files. There are no OFX specific libraries to link against as the APIs consists solely of sets of header files and their supporting documentation. The API is also designed to minimise symbolic dependencies between the host and the plug-in.

Certain concepts are at the core of the OFX plug-in architecture, these are APIs, actions, suites, properties and handles. No matter what kind of API is being built on top of the core architecture, it will use these objects.

OFX plug-ins are distributed as dynamically loadable shared libraries, the exact format is dependant upon the host operating system and is defined below. Each such binary can contain one or more OFX plug-ins .The whole set of OFX APIs bootstrap from two symbols inside a plug-in, these are OfxGetNumberOfPlugins and OfxGetPlugin.

int OfxGetNumberOfPlugins(void)

OfxPlugin * OfxGetPlugin(int nth)

A plug-in's description is bootstrapped by using the required OfxGetPlugin function. This function returns an OfxPlugin data structure which gives a basic description of the plug-in.

The following sequences of operations needs to be performed by a host before it can start telling a plug-in what to do via its mainEntry function.

OFX has a standard set of unsigned integer status codes used to indicate errors and general status. These are returned by most functions in the host suites and by the plug ins' entry points. The error codes returned by functions and actions are documented along side them.

It is an error to throw a C++ exception across the API, all exceptions should be trapped on either side of the API and an appropriate error code passed instead.

Where a host application chooses to search for OFX plug ins, what binary format they are in and any directory hierarchy is entirely up to it. However, it is strongly recommended that the following scheme be followed.

A clip simply a sequences of still images, played back at some frame rate to give the illusion of motion. Thank you Lumiere brothers. All applications that process moving images use clips in one form or another. A clip is typically a single set of images that are logically associated, for example they consist of a single shot from a motion picture.

An image is a 2D array of pixels. A set of input images are processed by an effect to produce an output image. bit depth components pixel aspect ratio bounds data