OpenFX Plug-in API Programming Guide

Table of Contents Foreword Intended Audience What is OFX 1. OFX Overview Language API Definition Symbolic Dependancies Host to Plugin Communication Host to Plugin Communication 2. Introduction To OFX, A Simple Plug-in Headers The Plug-in Struct and The Two Exported Functions The Host Struct The Main Entry Function The Load Action The Describe Action The Describe In Context Action The Render Action In Summary 3. The Generic OFX Plug-in Architecture Overview Plug-in Binaries and Required Symbols OfxGetNumberOfPlugins OfxGetPlugin Identifying, Versioning and Defining an OFX Plug-in The OfxPlugin Struct Interpreting the OfxPlugin Struct Suites, Hosts and APIs Function Suites The OfxHost Struct Sequences of Operations Required to Load a Plug-in Errors, Status Codes and Exceptions Packaging OFX Plug-ins Binary Types Installation Directory Hierarchy Installation Location plug-in Icons Externally Specified Resources 4. Visual Effects Architectures Clips Images Parameters Time Effects Contexts Co-ordinate Systems Regions of Definition and Regions of Interest 5. OFX Image Effect Plug-ins 6. Parameters

Foreword OFX is an open API for writing visual effects plug-ins for a wide variety of applications, such as video editing systems and compositing systems. It seems to have two interchangable names, "OpenFX" and "OFX". I prefer OFX for some reason. This book is actually very broad in scope, as it has to not only define the API, it will need to go into some depth describing concepts behind imaging applications that use it. UNFINISHED Intended Audience Do you write visual effects or image processing software? Do you have an application which deals with moving images and hosts plug-ins or would like to host plug-ins? Then OFX is for you. This book assumes you can program in the "C" language and are familiar with the concepts involved in writing visual effects software. You need to understand concepts like pixels, clips, pixel aspect ratios and more. If you don't, I suggest you read further or attempt to soldier on bravely and see how far you go before you get lost. What is OFX OFX is actually several things. At the lowest level OFX is a generic 'C' based plug-in architecture that can be used to define any kind of plug-in API. You could use this low level architecture to implement any API, however it was originally designed to host our visual effects image processing API. The basic architecture could be re-used to create other higher level APIs such as a sound effects API, a 3D API and more. This book describes the basic OFX plug-in architecture and the visual effects plug-in API built on top of it. The visual effects API is very broad and intended to allow visual effects plug-ins to work on a wide range of host applications, including compositing hosts, rotoscopers, encoding applications, colour grading hosts, editing hosts and more I haven't thought of yet. While all these type of applications process images, they often have very different work flows and present effects to a user in incompatible ways. OFX is an attempt to deal with all of these in a clear and consistent manner. Chapter 1. OFX Overview   This chapter provides a brief overview of the basic plug-in architecture and some of the reasoning behind it. It will touch lightly . Language 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. API Definition 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. Symbolic Dependancies 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. Host to Plugin Communication A host communicates with a plug-in via a Host to Plugin Communication A host communicates with a plug-in via a Chapter 2. Introduction To OFX, A Simple Plug-in   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. Headers #include #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... ofxCore.h which provides definitions for the underlying plug-in loading mechanisms ofxProperty.h which defines the property getting/setting suite ofxImageEffect.h which provides access to the image effect suite 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. The Plug-in Struct and The Two Exported Functions // 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... the kind of plug-in it is, in this case a kOfxImageEffectPluginApi . Which happens to be an image effect plug-in, the version of the API the plug-in was written to. In this case version 1 , the unique name of the plug-in. Used only to disambiguate the plug-in from all other plug-ins, not necessarily for human eyes, the major and minor version of the plug-in, in this case 1.0 , which allows for simplified upgrades to the plug-in, a function used to set an important data structure in the plug-in, the function which the host uses to send messages to the plug-in The Host Struct // 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. The Main Entry Function // 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. The Load Action 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 Describe Action // 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. The Describe In Context Action // 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. The Render Action // 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. In Summary 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. Chapter 3. The Generic OFX Plug-in Architecture Overview As explained in the introduction, OFX is actually several things, an underlying generic plug-in architecture, specific plug-in APIs defined using that architecture. 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 ofxCore.h which defines basic data structures used in loading and identifying plug-ins, ofxProperty.h which defines the suite used for fetching and setting properties on objects. 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. Actions An action is how a host communicates with a plug-in, e.g.: "render frame 10". Actions are labelled by strings passed to a plug-in's 'mainEntry' function. Suites A suite is how a plug-in communicates to a host. Suites are 'C' structs filled with pointers to functions, the plug-in calls these functions to perform certain tasks (e.g.: fetch an image). Handles Handles are blind data pointers that are passed back to a plug-in from a host. They represent various types of data (e.g.: a set of properties, an instance of an image effect and so on) and are how objects on the host side are referenced by a plug-in. The data pointers themselves are typed by declaring them as pointers to defined but undeclared C structs. Properties Properties are simple data types used to communicate information between a host and a plug-in. They avoid having to pass around C structs and so makes versioning and backwards compatibility easier. They are name/value pairs labelled with a C-string. Properties are accessed using the property suite found in ofxProperty.h. APIs An 'API', in the OFX sense, is a named set of suites, actions and supporting objects used to implement a type of plug-in. Currently there is only one API built on the core architecture, this is the OFX Image Effect API, which is labelled by the string "OfxImageEffectPluginAPI" Plug-in Binaries and Required Symbols 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. OfxGetNumberOfPlugins int OfxGetNumberOfPlugins(void) This function returns the number of plug-ins inside the given binary. This will be the first function called by a host after initially loading the binary. OfxGetPlugin OfxPlugin * OfxGetPlugin(int nth) This function returns an OfxPlugin struct which defines the nth plug-in to the host. The data structure returned should point to a static chunk of memory in the plug-in, as the host will make no attempt to free the returned data structure when the plug-in is unloaded. Typically this will be the called multiple times by the host, once for each plug-in that the plug-in says it contains. Identifying, Versioning and Defining an OFX Plug-in 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 OfxPlugin Struct This structure is returned by a plugin to identify itself to the host. typedef struct OfxPlugin { const char *pluginApi; int apiVersion; const char *pluginIdentifier; unsigned int pluginVersionMajor; unsigned int pluginVersionMinor; void (*setHost)(OfxHost *host); OfxPluginEntryPoint *mainEntry; } OfxPlugin; pluginApi This cstring tells the host what API the plug-in implements. apiVersion This integer tells the host which version of its API the plug-in implements. pluginIdentifier This is the globally unique name for the plug-in. pluginVersionMajor Major version of this plug-in, this gets incremented whenever software is changed and breaks backwards compatibility. pluginVersionMinor Minor version of this plug-in, this gets incremented when software is changed, but does not break backwards compatibility. setHost Function used to set the host pointer (see below) which allows the plug-in to fetch suites associated with the API it implements. mainEntry The plug-in function that takes messages from the host telling it to do things. Interpreting the OfxPlugin Struct When a host gets a pointer back from OfxGetPlugin, it examines the string pluginApi. This identifies what kind of plug-in it is. Currently there is only one publicly specified API that uses the OFX mechanism, this is "OfxImageEffectPluginAPI", which is the image effect API being discussed by this book. More APIs may be created at a future date, for example "OfxImageImportPluginAPI". Knowing the type of plug-in, the host then knows what suites and host handles are required for that plug-in and what functions the plug-in itself will have. The host passes a OfxHost structure appropriate to that plug-in via it's setHost function. This allows for the same basic architecture to support different plug-in types trivially. OFX explicitly versions plug-in APIs. By examining the apiVersion, the host knows exactly what set of functions the plug-in is going to supply and what version of what suites it will need to provide. This also allows plug ins to implement several versions of themselves in the same binary, so it can take advantages of new features in a V2 API, but present a V1 plug-in to older hosts that only support V1. If a host does not support the given plug-in type, or it does not support the given version it should simply ignore that plug-in. A plug-in needs to uniquely identify itself to a host. This is the job of pluginIdentifier. This null terminated ASCII C string should be unique among all plug-ins, it is not necessarily meant to convey a sensible name to an end user. The recommended format is the reverse domain name format of the developer, for example "uk.co.thefoundry", followed by the developer's unique name for the plug-in. e.g. "uk.co.thefoundry.F_Kronos". A plug-in (as opposed to the API it implements) is versioned with two separate integers in the OfxPlugin struct. They serve two separate functions and are, pluginVersionMajor flags the functionality contained within a plug-in, incrementing this number means that you have broken backwards compatibility of the plug-in. More specifically, this means a setup from an earlier version, when loaded into this version, will not yield the same result. pluginVersionMinor flags the release of a plug-in that does not break backwards compatibility, but otherwise enhances that plug-in. For example, increment this when you have fixed a bug or made it faster. If a host encounters multiple versions of the same plug-in it should, when creating a brand new instance, always use the version of a plug-in with the greatest major and minor version numbers, when loading a setup, always use the plug-in with the major version that matches the setup, but has the greatest minor number. A more concrete example of versioning, the plug-in identified by "org.wibble:Fred" is initially released as 1.0, however a few months later, wibble.org figured out how to make it faster and release it as 1.1. A year later, Fred can now do automatically what a user once needed to set five parameters up to do, thus making it much simpler to use. However this breaks backwards compatibility as the effect can no longer produce the same output as before, so wibble.org then release this as v2.0. A user's host might now have three versions of the Fred plug-in on it, v1.0, v1.1 and v2.0. When creating a new instance of the plug-in, the host should always use v2.0. When loading an old project which has a setup from a v1.x plug-in, it should always use the latest, in this case being v1.1 Note that plug-ins can change the set of parameters between minor version releases. If a plug-in does so, it should do so in a backwards compatible manner, such that the default value of any new parameter would yield the same results as previously. See the chapter below about parameters. Suites, Hosts and APIs Function Suites A function suite is simply a struct filled with function pointers. Below is some code from the memory allocation suite found in ofxMemory.h. #define kOfxMemorySuite "OfxMemorySuite" typedef struct OfxMemorySuiteV1 { OfxStatus (*memoryAlloc)(void *handle, size_t nBytes, void **allocatedData); OfxStatus (*memoryFree)(void *allocatedData); } OfxMemorySuiteV1; The use is fairly obvious, you call functions through the pointers in the struct. This has the effect of avoiding any symbolic dependencies from the plug-in to the host. Note two other things about this code listing. the suite has a cstring name associated with it, the suite is versioned, via the "V1" suffix appended to the struct tag and typedef. The explicit naming and versioning of suites is how a plug-in fetches one, by calling the fetchSuite function in the OfxHost struct which is passed to it during the boot strapping stage. The OfxHost Struct The OfxHost struct is how a host provides plug-ins with access to the various suites that make up the API they implement, as well as a host property set handle which a plug-in can ask questions of. The setHost function in the OfxPlugin struct is passed a pointer to an OfxHost as the first thing to boot-strapping plug-in/host communication. The struct looks like... typedef struct OfxHost { OfxPropertySetHandle host; void *(*fetchSuite)(OfxPropertySetHandle host, const char *suiteName, int suiteVersion); } OfxHost; The OfxHost contains two elements, host - a property set handle that holds a set of properties which describe the host for the plug-in's API fetchSuite - a function handle used to fetch function suites from the host that implement the plug-in's API The host property set handle in the OfxHost is not global across all plug-ins defined in the binary. It is only applicable for the plug-in whose 'setHost' function was called. Use this handle to fetch things like host application names, host capabilities and so on from. The set of properties on an OFX Image Effect host is found in the section Properties on the Image Effect Host The fetchSuite function is how a plug-in gets a suite from the host. It asks for a suite by giving the cstring corresponding to that suite and the version of that suite. The host will return a pointer to that suite, or NULL if it does not support it. Please note that suite cannot be fetched until the very first action is called on the plug-in. Which is the load action. Sequences of Operations Required to Load a 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. the binary containing the plug-in is loaded, the number of plug-ins is determined via the OfxGetNumberOfPlugins function, for each plug-in defined in the binary OfxGetPlugin is called, the pluginApi and apiVersion of the returned OfxPlugin struct are examined, if the plug-in's API or it's version are not supported, the plug-in is ignored and we skip to the next one, the plug-in's pointer is recorded in a plug-in cache an appropriate OfxHost struct is passed to the plug-in via setHost in the returned OfxPlugin struct. Errors, Status Codes and Exceptions 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. Packaging OFX Plug-ins 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. Binary Types Plug-ins should be distributed in the following formats, depending on the host operating system.... Microsoft Windows, as ".dll" dynamically linked libraries, Apple OSX, as Mach-O binary bundles, IRIX and LINUX, as ELF dynamic shared objects. Installation Directory Hierarchy Each plug-in binary is distributed as a Mac OS X package style directory hierarchy. Note that the there are two distinct meanings of 'bundle', one referring to a binary file format, the other to a directory hierarchy used to distribute software. We are distributing binaries in a bundle package, and in the case of OSX, the binary is a binary bundle. All the binaries must end with ".ofx", regardless of the host operating system. The directory hierarchy is as follows..... NAME.ofx.bundle Contents ARCHITECTURE_A NAME.ofx ARCHITECTURE_B NAME.ofx Info.plist Resources NAME.xml PLUGIN_A.png PLUGIN_B.png ... PLUGIN_N.png .... ARCHITECTURE_N NAME.ofx Where... Info.plist is relevant for OSX only and needs to be filled in appropriately, NAME is the file name you want the installed plug-in to be identified by, PLUGIN.png - is the image to use as an icon for the plug-in in the binary which has a matching pluginIdentifier field in the OfxPlugin struct, ARCHITECTURE is the specific operating system architecture the plug-in was built for, these are currently... MacOS - for Apple Macintosh OS X (compiled 32 bit) Win32 - for Microsoft Windows (compiled 32 bit) IRIX - for SGI IRIX plug-ins (compiled 32 bit) IRIX64 - for SGI IRIX plug-ins (compiled 64 bit) Linux-x86 - for Linux on intel x86 CPUs (compiled 32 bit) Linux-x86-64 - for Linux on intel x86 CPUs running AMD's 64 bit extensions Note that not all the above architectures need be supported, only at least one. This structure is necessary on OS X, but it also gives a nice skeleton to hang all other operating systems from in a single install, as well as a clean place to put resources. The Info.plist is specific to Apple and you should consult the Apple developer's website for more details. It should contain the following keys... CFBundleExecutable - the name of the binary bundle in the MacOS directory CFBundlePackageType - to be 'BNDL' CFBundleInfoDictionaryVersion CFBundleVersion CFBundleDevelopmentRegion Installation Location Plug ins are searched for in a variety of locations, both default and user specified. All such directories are examined for plug-in bundles and sub directories are also recursively examined. A list of directories is supplied in the "OFX_PLUGIN_PATH" environment variable, these are examined, first to last, for plug ins, then the default location is examined. On Microsoft Windows machines, the plug ins are searched for in, the ';' separated directory list specified by the environment variable "OFX_PLUGIN_PATH" the directory "C:\Program Files\Common Files\OFX\Plugins" On Apple OSX machines, the plug ins are searched for in, the ';' separated directory list specified by the environment variable "OFX_PLUGIN_PATH" the directory "/Library/OFX/Plugins" On UNIX, Linux and other UNIX like operating systems, the ':' separated directory specified by the environment variable "OFX_PLUGIN_PATH" the directory "/usr/OFX/Plugins" Any bundle or sub-directory name starting with the character '@' is to be ignored. Such directories or bundles must be skipped. Different versions of the same plug-in may be encountered in multiple locations, in which case, only the greatest minor version of each major version should be taken note of. For example: 3.2, 1.4 and 2.3 would be noted, but not 3.1, 1.3 or 2.0. If two copies of a plug-in with the same major and minor version are encountered, it can be assumed they are duplicates and all but the first one ignored. plug-in Icons Some hosts may wish to display an icon associated with a plug-in on their interfaces. Any such icon must be in the Portable Network Graphics format (see http://www.libpng.org/) and must contain 32 bits of colour, including an alpha channel. Ideally it should be at least 128x128 pixels. Host applications should dynamically resize the icon to fit their preferred icon size. The icon should not have it's aspect changed, rather the host should fill with some appropriate colour any blank areas due to aspect mis matches. Ideally plug-in developers should not render the plug-in's name into the icon, as this may be changed by the resource file, especially for internationalisation purposes. Hosts should thus present the plug-in's name next to the icon in some way. The icon file must be named as the corresponding pluginIdentifier field from the OfxPlugin, post pended with '.png' and be placed in the resources sub-directory. Externally Specified Resources Some plug-ins may supply an externally specified resource file. Typically this is for tasks such as internationalising interfaces, tweaking user interfaces for specific hosts and so on. These are XML files and have DTD associated with the specific API, for example OFX Image Effect DTD is found in ofx.dtd. The xml resource file is installed in the Resources sub directory of the bundle hierarchy. It's name will be NAME.xml, where name is the base name of the bundle folder and the effect binaries. Chapter 4. Visual Effects Architectures All applications that perform visual effects have certain basic similarities, unfortunately they also have many differences, and OFX needs to cope with them all. This chapter gives an overview of architectures and the concepts behind them. Feel free to skip it if you have experience of programming for a range of visual effects applications. The concepts are expressed in OFX terminology and may be somewhat different to how other systems express them Clips 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. bit depth components PAR Images 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 Parameters Time Effects Contexts Co-ordinate Systems Regions of Definition and Regions of Interest Chapter 5. OFX Image Effect Plug-ins An OFX image effect plug-in is one that uses the OFX Image Effect API to implement a visual effect. To do that it needs Chapter 6. Parameters