Actions Passed to a Mesh Effect#

OpenFX defines a unified way to interact with plug-ins through the notion of action. Actions passed to an OpenMfx’ plug-in main entry point are either some actions from OpenFX core, used with the same meaning, or dedicated actions.

For generic actions, the handle passed to to main entry point is an OfxMeshEffectHandle.

Actions specific to Mesh Effects#

kOfxMeshEffectActionCook#

This action is where an effect gets to compute geometry and turn its input mesh and parameter set into an output mesh. This is possibly quite complicated and covered in the “Cooking Mesh Effects” chapter.

The cook action must be trapped by the plug-in, it cannot return kOfxStatReplyDefault.

Return

  • kOfxStatOK, the effect cooked normally

  • 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

Parameters

  • handle: handle to the instance, cast to an OfxMeshEffectHandle

  • inArgs: has the following properties

    • kOfxPropTime the time at which to cook

  • outArgs: is redundant and should be set to NULL 

     \pre
    -  \ref kOfxActionCreateInstance has been called on the instance

kOfxMeshEffectActionIsIdentity#

Sometimes an effect can pass through an input unprocessed, for example a displace effect with a displace amplitude of 0. This action can be called by a host before it attempts to cook 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 geometry, it should set the value of the kOfxPropName to the input 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.

Return

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

  • kOfxStatReplyDefault, the action was not trapped and the host should call the cook 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

Parameters

  • handle: handle to the instance, cast to an OfxMeshEffectHandle

  • inArgs: has the following properties

    • kOfxPropTime the time at which to test for identity

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

    • kOfxPropName this to the name of the input that should be used if the effect is an identity transform, defaults to the empty string

    • kOfxPropTime the time to use from the indicated source input as an identity mesh (allowing time slips to happen), defaults to the value in kOfxPropTime in inArgs

Core OpenFX Actions supported by Mesh Effects#

These actions are already presented in the Image Effect OpenFX API but are listed here for the sake of completeness.

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

  • The plugin’s OfxPlugin::setHost function has been called

Post

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

Return

  • 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,

  • 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.

Return

  • kOfxStatOK, the action was trapped all was well

  • kOfxStatReplyDefault, the action was ignored

  • kOfxStatErrFatal, in which case we the program will be forced to quit

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.

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.

Return

  • kOfxStatOK, the action was trapped and all was well

  • kOfxStatErrMissingHostFeature, in which the plugin will be unloaded and ignored, plugin may post message

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

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

  • kOfxStatErrFatal

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

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.

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

Return

  • 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

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

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.

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

  • kOfxStatReplyDefault, the action was ignored as the effect had nothing to do,

  • kOfxStatErrFatal,

  • kOfxStatFailed, something went wrong, but no error code appropriate, the plugin should to post a message.

Pre

Post

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

Return

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.

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