Actions Passed to An Image Effect

The Generic Load Action
kOfxActionLoad 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.
SUPPORTED

The Generic Unload Action
kOfxActionUnload 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.
SUPPORTED

The Generic Describe Action
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.
SUPPORTED

The Generic Create Instance Action
The kOfxActionCreateInstance 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.
SUPPORTED

The Generic Destroy Instance Action
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.
SUPPORTED

The Generic Begin/End Instance Changed Actions
kOfxActionBeginInstanceChanged and kOfxActionEndInstanceChanged 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.

SUPPORTED

The Generic Instance Changed Action
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.
SUPPORTED

The Generic Purge Caches Action
The kOfxActionPurgeCaches is an action that may be passed to a plug-in instance from time to time in low memory situations. Instances receiving 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.
SUPPORTED

The Sync Private Data Action
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.
SUPPORTED

The Generic Begin Instance Edit Action
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.
SUPPORTED

The Generic End Instance Edit Action
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.
SUPPORTED

The Describe In Context Action
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.
SUPPORTED

The Get Region of Definition Action
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.
SUPPORTED

The Get Regions Of Interest Action
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. Form more details see Image Effect Architectures.
SUPPORTED

The Get Frames Needed Action
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 kOfxImageEffectPropTemporalClipAccessg 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 acion is not called.
SUPPORTED

The Is Identity Action
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.
SUPPORTED

The Render Action
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.
SUPPORTED

The Begin Sequence Render Action
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.
SUPPORTED
The End Sequence Render Action
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.
SUPPORTED

The Get Clip Preferences Action
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.
SUPPORTED

The Get Time Domain Action
This action allows a host to ask an effect what range of frames it can produce images over. Only effects instantiated in the General Contextcan have this called on them. In all other the host is in strict control over the temporal duration of the effect.
SUPPORTED

Actions Passed to an Interact
The Describe Action
The kOfxActionDescribe is the first action passed to an interact. It is where an interact 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 interact.
SUPPORTED

The Create Instance Action
The kOfxActionCreateInstance is the first action passed to an interact instance after its creation. It is there to allow a plugin to create any per-instance data structures it may need.
SUPPORTED

The Destroy Instance Action
This action is the last passed to an interact's instance before its destruction. It is there to allow a plugin to destroy any per-instance data structures it may have created.
SUPPORTED
The Draw Action
This action is issued to an interact whenever the host needs the plugin to redraw the given interact. The interact should issue any openGL calls it needs at this point.
Note that the interact may (in the case of custom parameter GUIS) or may not (in the case of image effect overlays) be required to swap buffers, that is up to the kind of interact.
SUPPORTED
kOfxInteractActionPenMotion
This action is issued whenever the pen moves an the interact's has focus. It should be issued whether the pen is currently up or down.
No openGL calls should be issued by the plug-in during this action.
SUPPORTED
kOfxInteractActionPenDown
This action is issued when a pen transitions for the 'up' to the 'down' state.
No openGL calls should be issued by the plug-in during this action.
SUPPORTED
kOfxInteractActionPenUp
This action is issued when a pen transitions for the 'down' to the 'up' state.
No openGL calls should be issued by the plug-in during this action.
SUPPORTED
kOfxInteractActionKeyDown
This action is issued when a key on the keyboard is depressed.
No openGL calls should be issued by the plug-in during this action.
SUPPORTED
kOfxInteractActionKeyUp
This action is issued when a key on the keyboard is released.
No openGL calls should be issued by the plug-in during this action.
SUPPORTED
kOfxInteractActionKeyRepeat
This action is issued when a key on the keyboard is held down an a key repeat is issued.
No openGL calls should be issued by the plug-in during this action.
SUPPORTED
kOfxInteractActionGainFocus
This action is issued when an interact gains input focus.
No openGL calls should be issued by the plug-in during this action.
SUPPORTED
kOfxInteractActionLoseFocus
This action is issued when an interact loses input focus.
No openGL calls should be issued by the plug-in during this action.
SUPPORTED