Actions Passed to An Image Effect

Actions passed to an OFX Image Effect’s plug-in main entry point are from two categories…

  • actions that could potentially be issued to any kind of plug in, not just image effects, known as generic actions, found in ofxCore.h

  • actions that are only applicable purely to image effects, found in ofxImageEffect.h

For generic actions, the handle passed to to main entry point will depend on the API being implemented, for all generic actions passed to an OFX Image Effect plug-in, it will nearly always be an OfxImageEffectHandle.

Because interacts are a special case, they are dealt with in a separate chapter, this chapter will deal with actions issued to an image effect plug-ins main entry point.

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.

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:

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:

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.

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.

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:

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:

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:

kOfxImageEffectActionDescribeInContext

This action is unique to OFX Image Effect plug-ins. Because a plugin is able to exhibit different behaviour depending on the context of use, each separate context will need to be described individually. It is within this action that image effects describe which parameters and input clips it requires.

This action will be called multiple times, one for each of the contexts the plugin says it is capable of implementing. If a host does not support a certain context, then it need not call kOfxImageEffectActionDescribeInContext for that context.

This action must be trapped, it is not optional.

Parameters:
Pre:

Returns:

kOfxImageEffectActionGetRegionOfDefinition

The region of definition for an image effect is the rectangular section of the 2D image plane that it is capable of filling, given the state of its input clips and parameters. This action is used to calculate the RoD for a plugin instance at a given frame. For more details on regions of definition see Image Effect Architectures.

Note that hosts that have constant sized imagery need not call this action, only hosts that allow image sizes to vary need call this.

If the effect did not trap this, it means the host should use the default RoD instead, which depends on the context. This is…

  • generator context - defaults to the project window,

  • filter and paint contexts - defaults to the RoD of the ‘Source’ input clip at the given time,

  • transition context - defaults to the union of the RoDs of the ‘SourceFrom’ and ‘SourceTo’ input clips at the given time,

  • general context - defaults to the union of the RoDs of all the non optional input clips and the ‘Source’ input clip (if it exists and it is connected) at the given time, if none exist, then it is the project window

  • retimer context - defaults to the union of the RoD of the ‘Source’ input clip at the frame directly preceding the value of the ‘SourceTime’ double parameter and the frame directly after it

Parameters:

  • handle – handle to the instance, cast to an OfxImageEffectHandle

  • inArgs – has the following properties

  • outArgs – has the following property which the plug-in may set

Returns:

kOfxImageEffectActionGetRegionsOfInterest

This action allows a host to ask an effect, given a region I want to render, what region do you need from each of your input clips. In that way, depending on the host architecture, a host can fetch the minimal amount of the image needed as input. Note that there is a region of interest to be set in outArgs for each input clip that exists on the effect. For more details see Image EffectArchitectures”.

The default RoI is simply the value passed in on the kOfxImageEffectPropRegionOfInterest inArgs property set. All the RoIs in the outArgs property set must initialised to this value before the action is called.

Parameters:

  • handle – handle to the instance, cast to an OfxImageEffectHandle

  • inArgs – has the following properties

  • outArgs – has a set of 4 dimensional double properties, one for each of the input clips to the effect. The properties are each named OfxImageClipPropRoI_ with the clip name post pended, for example OfxImageClipPropRoI_Source. These are initialised to the default RoI.

Returns:

kOfxImageEffectActionGetFramesNeeded

This action lets the host ask the effect what frames are needed from each input clip to process a given frame. For example a temporal based degrainer may need several frames around the frame to render to do its work.

This action need only ever be called if the plugin has set the kOfxImageEffectPropTemporalClipAccess property on the plugin descriptor to be true. Otherwise the host assumes that the only frame needed from the inputs is the current one and this action is not called.

Note that each clip can have it’s required frame range specified, and that you can specify discontinuous sets of ranges for each clip, for example

// The effect always needs the initial frame of the source as well as the previous and current frame
double rangeSource[4];

// required ranges on the source
rangeSource[0] = 0; // we always need frame 0 of the source
rangeSource[1] = 0;
rangeSource[2] = currentFrame - 1; // we also need the previous and current frame on the source
rangeSource[3] = currentFrame;

gPropHost->propSetDoubleN(outArgs, "OfxImageClipPropFrameRange_Source", 4, rangeSource);

Which sets two discontinuous range of frames from the 'Source' clip
required as input.

The default frame range is simply the single frame, kOfxPropTime..kOfxPropTime, found on the inArgs property set. All the frame ranges in the outArgs property set must initialised to this value before the action is called.

Parameters:

  • handle – handle to the instance, cast to an OfxImageEffectHandle

  • inArgs – has the following property

    • kOfxPropTime the effect time for which we need to calculate the frames needed on input

    • outArgs has a set of properties, one for each input clip, named OfxImageClipPropFrameRange_ with the name of the clip post-pended. For example OfxImageClipPropFrameRange_Source. All these properties are multi-dimensional doubles, with the dimension is a multiple of two. Each pair of values indicates a continuous range of frames that is needed on the given input. They are all initalised to the default value.

Returns:

kOfxImageEffectActionIsIdentity

Sometimes an effect can pass through an input uprocessed, for example a blur effect with a blur size of 0. This action can be called by a host before it attempts to render an effect to determine if it can simply copy input directly to output without having to call the render action on the effect.

If the effect does not need to process any pixels, it should set the value of the kOfxPropName to the clip that the host should us as the output instead, and the kOfxPropTime property on outArgs to be the time at which the frame should be fetched from a clip.

The default action is to call the render action on the effect.

Parameters:
Returns:

  • kOfxStatOK, the action was trapped and the effect should not have its render action called, the values in outArgs indicate what frame from which clip to use instead

  • kOfxStatReplyDefault, the action was not trapped and the host should call the render action

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

  • kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message

  • kOfxStatErrFatal

kOfxImageEffectActionRender

This action is where an effect gets to push pixels and turn its input clips and parameter set into an output image. This is possibly quite complicated and covered in the Rendering Image Effects chapter.

The render action must be trapped by the plug-in, it cannot return kOfxStatReplyDefault. The pixels needs be pushed I’m afraid.

Parameters:
Pre:

Post:

Returns:

kOfxImageEffectActionBeginSequenceRender

This action is passed to an image effect before it renders a range of frames. It is there to allow an effect to set things up for a long sequence of frames. Note that this is still called, even if only a single frame is being rendered in an interactive environment.

Parameters:
Pre:

Post:

Returns:

kOfxImageEffectActionEndSequenceRender

This action is passed to an image effect after is has rendered a range of frames. It is there to allow an effect to free resources after a long sequence of frame renders. Note that this is still called, even if only a single frame is being rendered in an interactive environment.

Parameters:
Pre:

Returns:

kOfxImageEffectActionGetClipPreferences

This action allows a plugin to dynamically specify its preferences for input and output clips. Please see Image Effect Clip Preferences for more details on the behaviour. Clip preferences are constant for the duration of an effect, so this action need only be called once per clip, not once per frame.

This should be called once after creation of an instance, each time an input clip is changed, and whenever a parameter named in the kOfxImageEffectPropClipPreferencesSlaveParam has its value changed.

Parameters:

  • handle – handle to the instance, cast to an OfxImageEffectHandle

  • inArgs – is redundant and is set to NULL

  • outArgs – has the following properties which the plugin can set

    • a set of char * X 1 properties, one for each of the input clips currently attached and the output clip, labelled with OfxImageClipPropComponents_ post pended with the clip’s name. This must be set to one of the component types which the host supports and the effect stated it can accept on that input

    • a set of char * X 1 properties, one for each of the input clips currently attached and the output clip, labelled with OfxImageClipPropDepth_ post pended with the clip’s name. This must be set to one of the pixel depths both the host and plugin supports

    • a set of double X 1 properties, one for each of the input clips currently attached and the output clip, labelled with OfxImageClipPropPAR_ post pended with the clip’s name. This is the pixel aspect ratio of the input and output clips. This must be set to a positive non zero double value,

    • kOfxImageEffectPropFrameRate the frame rate of the output clip, this must be set to a positive non zero double value

    • kOfxImageClipPropFieldOrder the fielding of the output clip

    • kOfxImageEffectPropPreMultiplication the premultiplication of the output clip

    • kOfxImageClipPropContinuousSamples whether the output clip can produce different images at non-frame intervals, defaults to false,

    • kOfxImageEffectFrameVarying whether the output clip can produces different images at different times, even if all parameters and inputs are constant, defaults to false.

Returns:

  • kOfxStatOK, the action was trapped and at least one of the properties in the outArgs was changed from its default value

  • kOfxStatReplyDefault, the action was not trapped and the host should use the default values

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

  • kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message

  • kOfxStatErrFatal

kOfxImageEffectActionGetTimeDomain

This action allows a host to ask an effect what range of frames it can produce images over. Only effects instantiated in the GeneralContext” can have this called on them. In all other the host is in strict control over the temporal duration of the effect.

The default is:

  • the union of all the frame ranges of the non optional input clips,

  • infinite if there are no non optional input clips.

Parameters:
Pre:

  • kOfxActionCreateInstance has been called on the instance

  • the effect instance has been created in the general effect context

Returns: