File ofxCore.h

Contains the core OFX architectural struct and function definitions. For more details on the basic OFX architecture, see Architecture.

Defines

OfxExport

Platform independent export macro.

This macro is to be used before any symbol that is to be exported from a plug-in. This is OS/compiler dependent.

kOfxActionLoad

This action is the first action passed to a plug-in after the binary containing the plug-in has been loaded. It is there to allow a plug-in to create any global data structures it may need and is also when the plug-in should fetch suites from the host.

The handle, inArgs and outArgs arguments to the mainEntry are redundant and should be set to NULL.

Pre:

Post:

This action will not be called again while the binary containing the plug-in remains loaded.

Returns:

  • kOfxStatOK, the action was trapped and all was well,

  • kOfxStatReplyDefault, the action was ignored,

  • kOfxStatFailed

    , the load action failed, no further actions will be passed to the plug-in. Interpret if possible kOfxStatFailed as plug-in indicating it does not want to load Do not create an entry in the host’s UI for plug-in then.

    Plug-in also has the option to return 0 for OfxGetNumberOfPlugins or kOfxStatFailed if host supports OfxSetHost in which case kOfxActionLoad will never be called.

  • kOfxStatErrFatal, fatal error in the plug-in.

kOfxActionDescribe

The kOfxActionDescribe is the second action passed to a plug-in. It is where a plugin defines how it behaves and the resources it needs to function.

Note that the handle passed in acts as a descriptor for, rather than an instance of the plugin. The handle is global and unique. The plug-in is at liberty to cache the handle away for future reference until the plug-in is unloaded.

Most importantly, the effect must set what image effect contexts it is capable of working in.

This action must be trapped, it is not optional.

Parameters:

  • handle – handle to the plug-in descriptor, cast to an OfxImageEffectHandle

  • inArgs – is redundant and is set to NULL

  • outArgs – is redundant and is set to NULL

Pre:

Post:

  • kOfxActionDescribe will not be called again, unless it fails and returns one of the error codes where the host is allowed to attempt the action again

  • the handle argument, being the global plug-in description handle, is a valid handle from the end of a sucessful describe action until the end of the kOfxActionUnload action (ie: the plug-in can cache it away without worrying about it changing between actions).

  • kOfxImageEffectActionDescribeInContext will be called once for each context that the host and plug-in mutually support. If a plug-in does not report to support any context supported by host, host should not enable the plug-in.

Returns:

kOfxActionUnload

This action is the last action passed to the plug-in before the binary containing the plug-in is unloaded. It is there to allow a plug-in to destroy any global data structures it may have created.

The handle, inArgs and outArgs arguments to the main entry are redundant and should be set to NULL.

Pre:

  • the kOfxActionLoad action has been called

  • all instances of a plugin have been destroyed

Post:

  • No other actions will be called.

Returns:

kOfxActionPurgeCaches

This action is an action that may be passed to a plug-in instance from time to time in low memory situations. Instances recieving this action should destroy any data structures they may have and release the associated memory, they can later reconstruct this from the effect’s parameter set and associated information.

For Image Effects, it is generally a bad idea to call this after each render, but rather it should be called after kOfxImageEffectActionEndSequenceRender Some effects, typically those flagged with the kOfxImageEffectInstancePropSequentialRender property, may need to cache information from previously rendered frames to function correctly, or have data structures that are expensive to reconstruct at each frame (eg: a particle system). Ideally, such effect should free such structures during the kOfxImageEffectActionEndSequenceRender action.

Parameters:

  • handle – handle to the plug-in instance, cast to an OfxImageEffectHandle

  • inArgs – is redundant and is set to NULL

  • outArgs – is redundant and is set to NULL

Pre:

Returns:

kOfxActionSyncPrivateData

This action is called when a plugin should synchronise any private data structures to its parameter set. This generally occurs when an effect is about to be saved or copied, but it could occur in other situations as well.

Parameters:

  • handle – handle to the plug-in instance, cast to an OfxImageEffectHandle

  • inArgs – is redundant and is set to NULL

  • outArgs – is redundant and is set to NULL

Pre:

Post:

  • Any private state data can be reconstructed from the parameter set,

Returns:

kOfxActionCreateInstance

This action is the first action passed to a plug-in’s instance after its creation. It is there to allow a plugin to create any per-instance data structures it may need.

Parameters:

  • handle – handle to the plug-in instance, cast to an OfxImageEffectHandle

  • inArgs – is redundant and is set to NULL

  • outArgs – is redundant and is set to NULL

Pre:

  • kOfxActionDescribe has been called

  • the instance is fully constructed, with all objects requested in the describe actions (eg, parameters and clips) have been constructed and have had their initial values set. This means that if the values are being loaded from an old setup, that load should have taken place before the create instance action is called.

Post:

  • the instance pointer will be valid until the kOfxActionDestroyInstance action is passed to the plug-in with the same instance handle

Returns:

  • kOfxStatOK, the action was trapped and all was well

  • kOfxStatReplyDefault, the action was ignored, but all was well anyway

  • kOfxStatErrFatal

  • kOfxStatErrMemory, in which case this may be called again after a memory purge

  • kOfxStatFailed, something went wrong, but no error code appropriate, the plugin should to post a message if possible and the host should destroy the instanace handle and not attempt to proceed further

kOfxActionDestroyInstance

This action is the last passed to a plug-in’s instance before its destruction. It is there to allow a plugin to destroy any per-instance data structures it may have created.

Parameters:

  • handle – handle to the plug-in instance, cast to an OfxImageEffectHandle

  • inArgs – is redundant and is set to NULL

  • outArgs – is redundant and is set to NULL

Pre:

Post:

  • the instance pointer is no longer valid and any operation on it will be undefined

Returns:

To some extent, what is returned is moot, a bit like throwing an exception in a C++ destructor, so the host should continue destruction of the instance regardless.

kOfxActionInstanceChanged

This action signals that something has changed in a plugin’s instance, either by user action, the host or the plugin itself. All change actions are bracketed by a pair of kOfxActionBeginInstanceChanged and kOfxActionEndInstanceChanged actions. The inArgs property set is used to determine what was the thing inside the instance that was changed.

Parameters:

  • handle – handle to the plug-in instance, cast to an OfxImageEffectHandle

  • inArgs – has the following properties

    • kOfxPropType The type of the thing that changed which will be one of..

    • kOfxTypeParameter Indicating a parameter’s value has changed in some way

    • kOfxTypeClip A clip to an image effect has changed in some way (for Image Effect Plugins only)

    • kOfxPropName the name of the thing that was changed in the instance

    • kOfxPropChangeReason what triggered the change, which will be one of…

    • kOfxChangeUserEdited - the user or host changed the instance somehow and caused a change to something, this includes undo/redos, resets and loading values from files or presets,

    • kOfxChangePluginEdited - the plugin itself has changed the value of the instance in some action

    • kOfxChangeTime - the time has changed and this has affected the value of the object because it varies over time

    • kOfxPropTime

    • the effect time at which the chang occured (for Image Effect Plugins only)

    • kOfxImageEffectPropRenderScale

    • the render scale currently being applied to any image fetched from a clip (for Image Effect Plugins only)

  • outArgs – is redundant and is set to NULL

Pre:

Post:

Returns:

kOfxActionBeginInstanceChanged

The kOfxActionBeginInstanceChanged and kOfxActionEndInstanceChanged actions are used to bracket all kOfxActionInstanceChanged actions, whether a single change or multiple changes. Some changes to a plugin instance can be grouped logically (eg: a ‘reset all’ button resetting all the instance’s parameters), the begin/end instance changed actions allow a plugin to respond appropriately to a large set of changes. For example, a plugin that maintains a complex internal state can delay any changes to that state until all parameter changes have completed.

Parameters:

  • handle – handle to the plug-in instance, cast to an OfxImageEffectHandle

  • inArgs – has the following properties

    • kOfxPropChangeReason what triggered the change, which will be one of…

    • kOfxChangeUserEdited - the user or host changed the instance somehow and caused a change to something, this includes undo/redos, resets and loading values from files or presets,

    • kOfxChangePluginEdited - the plugin itself has changed the value of the instance in some action

    • kOfxChangeTime - the time has changed and this has affected the value of the object because it varies over time

  • outArgs – is redundant and is set to NULL

Post:

Post:

Returns:

kOfxActionEndInstanceChanged

Action called after the end of a set of kOfxActionEndInstanceChanged actions, used with kOfxActionBeginInstanceChanged to bracket a grouped set of changes, see kOfxActionBeginInstanceChanged.

kOfxActionBeginInstanceEdit

This is called when an instance is first actively edited by a user, ie: and interface is open and parameter values and input clips can be modified. It is there so that effects can create private user interface structures when necassary. Note that some hosts can have multiple editors open on the same effect instance simulateously.

Parameters:

  • handle – handle to the plug-in instance, cast to an OfxImageEffectHandle

  • inArgs – is redundant and is set to NULL

  • outArgs – is redundant and is set to NULL

Pre:

Post:

Returns:

kOfxActionEndInstanceEdit

This is called when the last user interface on an instance closed. It is there so that effects can destroy private user interface structures when necassary. Note that some hosts can have multiple editors open on the same effect instance simulateously, this will only be called when the last of those editors are closed.

Parameters:

  • handle – handle to the plug-in instance, cast to an OfxImageEffectHandle

  • inArgs – is redundant and is set to NULL

  • outArgs – is redundant and is set to NULL

Pre:

Post:

  • no user interface is open on the instance

Returns:

kOfxPropAPIVersion

Property on the host descriptor, saying what API version of the API is being implemented.

  • Type - int X N

  • Property Set - host descriptor.

This is a version string that will specify which version of the API is being implemented by a host. It can have multiple values. For example “1.0”, “1.2.4” etc…..

If this is not present, it is safe to assume that the version of the API is “1.0”.

kOfxPropTime

General property used to get/set the time of something.

  • Type - double X 1

  • Default - 0, if a setable property

  • Property Set - commonly used as an argument to actions, input and output.

kOfxPropIsInteractive

Indicates if a host is actively editing the effect with some GUI.

  • Type - int X 1

  • Property Set - effect instance (read only)

  • Valid Values - 0 or 1

If false the effect currently has no interface, however this may be because the effect is loaded in a background render host, or it may be loaded on an interactive host that has not yet opened an editor for the effect.

The output of an effect should only ever depend on the state of its parameters, not on the interactive flag. The interactive flag is more a courtesy flag to let a plugin know that it has an interace. If a plugin want’s to have its behaviour dependant on the interactive flag, it can always make a secret parameter which shadows the state if the flag.

kOfxPluginPropFilePath

The file path to the plugin.

  • Type - C string X 1

  • Property Set - effect descriptor (read only)

This is a string that indicates the file path where the plug-in was found by the host. The path is in the native path format for the host OS (eg: UNIX directory separators are forward slashes, Windows ones are backslashes).

The path is to the bundle location, see InstallationLocation. eg: ‘/usr/OFX/Plugins/AcmePlugins/AcmeFantasticPlugin.ofx.bundle’

kOfxPropInstanceData

A private data pointer that the plug-in can store its own data behind.

  • Type - pointer X 1

  • Property Set - plugin instance (read/write),

  • Default - NULL

This data pointer is unique to each plug-in instance, so two instances of the same plug-in do not share the same data pointer. Use it to hang any needed private data structures.

kOfxPropType

General property, used to identify the kind of an object behind a handle.

kOfxPropName

Unique name of an object.

  • Type - ASCII C string X 1

  • Property Set - on many objects (descriptors and instances), see PropertiesByObject (read only)

This property is used to label objects uniquely amoung objects of that type. It is typically set when a plugin creates a new object with a function that takes a name.

kOfxPropVersion

Identifies a specific version of a host or plugin.

  • Type - int X N

  • Property Set - host descriptor (read only), plugin descriptor (read/write)

  • Default - “0”

  • Valid Values - positive integers

This is a multi dimensional integer property that represents the version of a host (host descriptor), or plugin (plugin descriptor). These represent a version number of the form ‘1.2.3.4’, with each dimension adding another ‘dot’ on the right.

A version is considered to be more recent than another if its ordered set of values is lexicographically greater than another, reading left to right. (ie: 1.2.4 is smaller than 1.2.6). Also, if the number of dimensions is different, then the values of the missing dimensions are considered to be zero (so 1.2.4 is greater than 1.2).

kOfxPropVersionLabel

Unique user readable version string of a plugin or host.

  • Type - string X 1

  • Property Set - host descriptor (read only), plugin descriptor (read/write)

  • Default - none, the host needs to set this

  • Valid Values - ASCII string

This is purely for user feedback, a plugin or host should use kOfxPropVersion if they need to check for specific versions.

kOfxPropPluginDescription

Description of the plug-in to a user.

  • Type - string X 1

  • Property Set - plugin descriptor (read/write) and instance (read only)

  • Default - “”

  • Valid Values - UTF8 string

This is a string giving a potentially verbose description of the effect.

kOfxPropLabel

User visible name of an object.

  • Type - UTF8 C string X 1

  • Property Set - on many objects (descriptors and instances), see PropertiesByObject. Typically readable and writable in most cases.

  • Default - the kOfxPropName the object was created with.

The label is what a user sees on any interface in place of the object’s name.

Note that resetting this will also reset kOfxPropShortLabel and kOfxPropLongLabel.

kOfxPropIcon

If set this tells the host to use an icon instead of a label for some object in the interface.

  • Type - string X 2

  • Property Set - various descriptors in the API

  • Default - “”

  • Valid Values - ASCII string

The value is a path is defined relative to the Resource folder that points to an SVG or PNG file containing the icon.

The first dimension, if set, will the name of and SVG file, the second a PNG file.

kOfxPropShortLabel

Short user visible name of an object.

  • Type - UTF8 C string X 1

  • Property Set - on many objects (descriptors and instances), see PropertiesByObject. Typically readable and writable in most cases.

  • Default - initially kOfxPropName, but will be reset if kOfxPropLabel is changed.

This is a shorter version of the label, typically 13 character glyphs or less. Hosts should use this if they have limitted display space for their object labels.

kOfxPropLongLabel

Long user visible name of an object.

  • Type - UTF8 C string X 1

  • Property Set - on many objects (descriptors and instances), see PropertiesByObject. Typically readable and writable in most cases.

  • Default - initially kOfxPropName, but will be reset if kOfxPropLabel is changed.

This is a longer version of the label, typically 32 character glyphs or so. Hosts should use this if they have mucg display space for their object labels.

kOfxPropChangeReason

Indicates why a plug-in changed.

  • Type - ASCII C string X 1

  • Property Set - inArgs parameter on the kOfxActionInstanceChanged action.

  • Valid Values - this can be…

    • kOfxChangeUserEdited - the user directly edited the instance somehow and caused a change to something, this includes undo/redos and resets

    • kOfxChangePluginEdited - the plug-in itself has changed the value of the object in some action

    • kOfxChangeTime - the time has changed and this has affected the value of the object because it varies over time

Argument property for the kOfxActionInstanceChanged action.

kOfxPropEffectInstance

A pointer to an effect instance.

  • Type - pointer X 1

  • Property Set - on an interact instance (read only)

This property is used to link an object to the effect. For example if the plug-in supplies an openGL overlay for an image effect, the interact instance will have one of these so that the plug-in can connect back to the effect the GUI links to.

kOfxPropHostOSHandle

A pointer to an operating system specific application handle.

  • Type - pointer X 1

  • Property Set - host descriptor.

Some plug-in vendor want raw OS specific handles back from the host so they can do interesting things with host OS APIs. Typically this is to control windowing properly on Microsoft Windows. This property returns the appropriate ‘root’ window handle on the current operating system. So on Windows this would be the hWnd of the application main window.

kOfxChangeUserEdited

String used as a value to kOfxPropChangeReason to indicate a user has changed something.

kOfxChangePluginEdited

String used as a value to kOfxPropChangeReason to indicate the plug-in itself has changed something.

kOfxChangeTime

String used as a value to kOfxPropChangeReason to a time varying object has changed due to a time change.

kOfxFlagInfiniteMax

Used to flag infinite rects. Set minimums to this to indicate infinite.

This is effectively INT_MAX.

kOfxFlagInfiniteMin

Used to flag infinite rects. Set minimums to this to indicate infinite.

This is effectively INT_MIN

kOfxBitDepthNone

String used to label unset bitdepths.

kOfxBitDepthByte

String used to label unsigned 8 bit integer samples.

kOfxBitDepthShort

String used to label unsigned 16 bit integer samples.

kOfxBitDepthHalf

String used to label half-float (16 bit floating point) samples.

Version

Added in Version 1.4. Was in ofxOpenGLRender.h before.

kOfxBitDepthFloat

String used to label signed 32 bit floating point samples.

kOfxStatOK

Status code indicating all was fine.

kOfxStatFailed

Status error code for a failed operation.

kOfxStatErrFatal

Status error code for a fatal error.

Only returned in the case where the plug-in or host cannot continue to function and needs to be restarted.

kOfxStatErrUnknown

Status error code for an operation on or request for an unknown object.

kOfxStatErrMissingHostFeature

Status error code returned by plug-ins when they are missing host functionality, either an API or some optional functionality (eg: custom params).

Plug-Ins returning this should post an appropriate error message stating what they are missing.

kOfxStatErrUnsupported

Status error code for an unsupported feature/operation.

kOfxStatErrExists

Status error code for an operation attempting to create something that exists.

kOfxStatErrFormat

Status error code for an incorrect format.

kOfxStatErrMemory

Status error code indicating that something failed due to memory shortage.

kOfxStatErrBadHandle

Status error code for an operation on a bad handle.

kOfxStatErrBadIndex

Status error code indicating that a given index was invalid or unavailable.

kOfxStatErrValue

Status error code indicating that something failed due an illegal value.

kOfxStatReplyYes

OfxStatus returned indicating a ‘yes’.

kOfxStatReplyNo

OfxStatus returned indicating a ‘no’.

kOfxStatReplyDefault

OfxStatus returned indicating that a default action should be performed.

Typedefs

typedef struct OfxPropertySetStruct *OfxPropertySetHandle

Blind data structure to manipulate sets of properties through.

typedef int OfxStatus

OFX status return type.

typedef struct OfxHost OfxHost

Generic host structure passed to OfxPlugin::setHost function.

This structure contains what is needed by a plug-in to bootstrap its connection to the host.

OfxStatus() OfxPluginEntryPoint (const char *action, const void *handle, OfxPropertySetHandle inArgs, OfxPropertySetHandle outArgs)

Entry point for plug-ins.

  • action ASCII c string indicating which action to take

  • instance object to which action should be applied, this will need to be cast to the appropriate blind data type depending on the action

  • inData handle that contains action specific properties

  • outData handle where the plug-in should set various action specific properties

This is how the host generally communicates with a plug-in. Entry points are used to pass messages to various objects used within OFX. The main use is within the OfxPlugin struct.

The exact set of actions is determined by the plug-in API that is being implemented, however all plug-ins can perform several actions. For the list of actions consult OFX Actions.

typedef struct OfxPlugin OfxPlugin

The structure that defines a plug-in to a host.

This structure is the first element in any plug-in structure using the OFX plug-in architecture. By examining its members a host can determine the API that the plug-in implements, the version of that API, its name and version.

For details see Architecture.

typedef double OfxTime

How time is specified within the OFX API.

typedef struct OfxRangeI OfxRangeI

Defines one dimensional integer bounds.

typedef struct OfxRangeD OfxRangeD

Defines one dimensional double bounds.

typedef struct OfxPointI OfxPointI

Defines two dimensional integer point.

typedef struct OfxPointD OfxPointD

Defines two dimensional double point.

typedef struct OfxRectI OfxRectI

Defines two dimensional integer region.

Regions are x1 <= x < x2

Infinite regions are flagged by setting

typedef struct OfxRectD OfxRectD

Defines two dimensional double region.

Regions are x1 <= x < x2

Infinite regions are flagged by setting

Functions

OfxPlugin *OfxGetPlugin(int nth)

Returns the ‘nth’ plug-in implemented inside a binary.

Returns a pointer to the ‘nth’ plug-in implemented in the binary. A function of this type must be implemented in and exported from each plug-in binary.

int OfxGetNumberOfPlugins(void)

Defines the number of plug-ins implemented inside a binary.

A host calls this to determine how many plug-ins there are inside a binary it has loaded. A function of this type must be implemented in and exported from each plug-in binary.

OfxStatus OfxSetHost(const OfxHost *host)

First thing host should call.

This host call, added in 2020, is not specified in earlier implementation of the API. Therefore host must check if the plugin implemented it and not assume symbol exists. The order of calls is then: 1) OfxSetHost, 2) OfxGetNumberOfPlugins, 3) OfxGetPlugin The host pointer is only assumed valid until OfxGetPlugin where it might get reset. Plug-in can return kOfxStatFailed to indicate it has nothing to do here, it’s not for this Host and it should be skipped silently.

struct OfxHost
#include <ofxCore.h>

Generic host structure passed to OfxPlugin::setHost function.

This structure contains what is needed by a plug-in to bootstrap its connection to the host.

Public Members

OfxPropertySetHandle host

Global handle to the host. Extract relevant host properties from this. This pointer will be valid while the binary containing the plug-in is loaded.

const void *(*fetchSuite)(OfxPropertySetHandle host, const char *suiteName, int suiteVersion)

The function which the plug-in uses to fetch suites from the host.

  • host the host the suite is being fetched from this must be the host member of the OfxHost struct containing fetchSuite.

  • suiteName ASCII string labelling the host supplied API

  • suiteVersion version of that suite to fetch

Any API fetched will be valid while the binary containing the plug-in is loaded.

Repeated calls to fetchSuite with the same parameters will return the same pointer.

It is recommended that hosts should return the same host and suite pointers to all plugins in the same shared lib or bundle.

returns

  • NULL if the API is unknown (either the api or the version requested),

  • pointer to the relevant API if it was found

struct OfxPlugin
#include <ofxCore.h>

The structure that defines a plug-in to a host.

This structure is the first element in any plug-in structure using the OFX plug-in architecture. By examining its members a host can determine the API that the plug-in implements, the version of that API, its name and version.

For details see Architecture.

Public Members

const char *pluginApi

Defines the type of the plug-in, this will tell the host what the plug-in does. e.g.: an image effects plug-in would be a “OfxImageEffectPlugin”

int apiVersion

Defines the version of the pluginApi that this plug-in implements

const char *pluginIdentifier

String that uniquely labels the plug-in among all plug-ins that implement an API. It need not necessarily be human sensible, however the preference is to use reverse internet domain name of the developer, followed by a ‘.’ then by a name that represents the plug-in.. It must be a legal ASCII string and have no whitespace in the name and no non printing chars. For example “uk.co.somesoftwarehouse.myPlugin”

unsigned int pluginVersionMajor

Major version of this plug-in, this gets incremented when backwards compatibility is broken.

unsigned int pluginVersionMinor

Major version of this plug-in, this gets incremented when software is changed, but does not break backwards compatibility.

void (*setHost)(OfxHost *host)

Function the host uses to connect the plug-in to the host’s api fetcher.

  • fetchApi pointer to host’s API fetcher

Mandatory function.

The very first function called in a plug-in. The plug-in must not call any OFX functions within this, it must only set its local copy of the host pointer.

It is recommended that hosts should return the same host and suite pointers to all plugins in the same shared lib or bundle.

Pre:

  • nothing else has been called

Post:

  • the pointer suite is valid until the plug-in is unloaded

OfxPluginEntryPoint *mainEntry

Main entry point for plug-ins.

Mandatory function.

The exact set of actions is determined by the plug-in API that is being implemented, however all plug-ins can perform several actions. For the list of actions consult OFX Actions.

Preconditions

  • setHost has been called

struct OfxRangeI
#include <ofxCore.h>

Defines one dimensional integer bounds.

Public Members

int min
int max
struct OfxRangeD
#include <ofxCore.h>

Defines one dimensional double bounds.

Public Members

double min
double max
struct OfxPointI
#include <ofxCore.h>

Defines two dimensional integer point.

Public Members

int x
int y
struct OfxPointD
#include <ofxCore.h>

Defines two dimensional double point.

Public Members

double x
double y
struct OfxRectI
#include <ofxCore.h>

Defines two dimensional integer region.

Regions are x1 <= x < x2

Infinite regions are flagged by setting

Public Members

int x1
int y1
int x2
int y2
struct OfxRectD
#include <ofxCore.h>

Defines two dimensional double region.

Regions are x1 <= x < x2

Infinite regions are flagged by setting

Public Members

double x1
double y1
double x2
double y2