.. _OfxPlugin:

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 C string 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 its ``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.

As 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 figure 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 up five parameters 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.


.. doxygenstruct: OfxPlugin