This chapter describes the actions that can be issued to an interact’s main entry point. Interact actions are also generic in character, they could be issued to other plug-in types rather than just Image Effects, however they are not issued directly to an effect’s main entry point, they are rather issued to separate entry points which exist on specific ‘interact’
objects that a plugin may create.
For nearly all the actions the handle passed to to main entry point for an interact will be either NULL, or a value that should be cast to anOfxInteractHandle.
kOfxActionDescribeInteract
This action is the first action passed to an interact. It is where an interact defines how it behaves and the resources it needs to function. If not trapped, the default action is for the host to carry on as normal Note that the handle passed in acts as a descriptor for, rather than an instance of the interact.
Pre
• The plugin has been loaded and the effect described.
Return
• kOfxStatOKthe action was trapped and all was well
• kOfxStatErrMemoryin which case describe may be called again after a memory purge
• kOfxStatFailedsomething was wrong, the host should ignore the interact
• kOfxStatErrFatal Parameters
• handle: handle to the interact descriptor, cast to anOfxInteractHandle
• inArgs: is redundant and is set to NULL
• outArgs: is redundant and is set to NULL kOfxActionCreateInstanceInteract
This action 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.
Pre
• kOfxActionDescribehas been called on this interact Post
• the instance pointer will be valid until thekOfxActionDestroyInstanceaction is passed to the plug-in with the same instance handle
Return
• kOfxStatOKthe action was trapped and all was well
• kOfxStatReplyDefaultthe action was ignored, but all was well anyway
• kOfxStatErrFatal
• kOfxStatErrMemoryin which case this may be called again after a memory purge
• kOfxStatFailedin which case the host should ignore this interact Parameters
• handle: handle to the interact instance, cast to anOfxInteractHandle
• inArgs: is redundant and is set to NULL
• outArgs: is redundant and is set to NULL kOfxActionDestroyInstanceInteract
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.
Pre
• kOfxActionCreateInstancehas been called on the handle,
• the instance has not had any of its members destroyed yet 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
• kOfxStatOKthe action was trapped and all was well
• kOfxStatReplyDefaultthe action was ignored as the effect had nothing to do
• kOfxStatErrFatal
• kOfxStatFailedsomething went wrong, but no error code appropriate.
Parameters
• handle: handle to the interact instance, cast to anOfxInteractHandle
• inArgs: is redundant and is set to NULL
• outArgs: is redundant and is set to NULL kOfxInteractActionDraw
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.
Pre
• kOfxActionCreateInstancehas been called on the instance handle
• the openGL context for this interact has been set
• the projection matrix will correspond to the interact’s cannonical view Return
• kOfxStatOKthe action was trapped and all was well
• kOfxStatReplyDefaultthe action was ignored
• kOfxStatErrFatal
• kOfxStatFailedsomething went wrong, the host should ignore this interact in future Parameters
• handle: handle to an interact instance, cast to anOfxInteractHandle
• inArgs: has the following properties on an image effect plugin
– kOfxPropEffectInstancea handle to the effect for which the interact has been,
– kOfxInteractPropPixelScalethe scale factor to convert cannonical pixels to screen pixels – kOfxInteractPropBackgroundColourthe background colour of the application behind the current
view
– kOfxPropTimethe effect time at which changed occured
– kOfxImageEffectPropRenderScalethe render scale applied to any image fetched
• outArgs: is redundant and is set to NULL 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.
Pre
• kOfxActionCreateInstancehas been called on the instance handle
• the current instance handle has hadkOfxInteractActionGainFocuscalled on it Post
• if the instance returnskOfxStatOK the host should not pass the pen motion to any other interactive object it may own that shares the same view.
Return
• kOfxStatOKthe action was trapped and the host should not pass the event to other objects it may own
• kOfxStatReplyDefaultthe action was not trapped and the host can deal with it if it wants Parameters
• handle: handle to an interact instance, cast to anOfxInteractHandle
• inArgs: has the following properties on an image effect plugin
– kOfxPropEffectInstancea handle to the effect for which the interact has been,
– kOfxInteractPropPixelScalethe scale factor to convert cannonical pixels to screen pixels – kOfxInteractPropBackgroundColourthe background colour of the application behind the current
view
– kOfxPropTimethe effect time at which changed occured
– kOfxImageEffectPropRenderScalethe render scale applied to any image fetched – kOfxInteractPropPenPositionpostion of the pen in,
– kOfxInteractPropPenViewportPositionposition of the pen in, – kOfxInteractPropPenPressurethe pressure of the pen,
• outArgs: is redundant and is set to NULL 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.
Pre
• kOfxActionCreateInstancehas been called on the instance handle,
• the current instance handle has hadkOfxInteractActionGainFocuscalled on it Post
• if the instance returnskOfxStatOK, the host should not pass the pen motion to any other interactive object it may own that shares the same view.
Return
• kOfxStatOK, the action was trapped and the host should not pass the event to other objects it may own
• kOfxStatReplyDefault, the action was not trapped and the host can deal with it if it wants Parameters
• handle: handle to an interact instance, cast to anOfxInteractHandle
• inArgs: has the following properties on an image effect plugin,
– kOfxPropEffectInstancea handle to the effect for which the interact has been,
– kOfxInteractPropPixelScalethe scale factor to convert cannonical pixels to screen pixels – kOfxInteractPropBackgroundColourthe background colour of the application behind the current
view
– kOfxPropTimethe effect time at which changed occured
– kOfxImageEffectPropRenderScalethe render scale applied to any image fetched – kOfxInteractPropPenPositionposition of the pen in
– kOfxInteractPropPenViewportPositionposition of the pen in – kOfxInteractPropPenPressurethe pressure of the pen
• outArgs: is redundant and is set to NULL 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.
Pre
• kOfxActionCreateInstancehas been called on the instance handle,
• the current instance handle has hadkOfxInteractActionGainFocuscalled on it Post
• if the instance returnskOfxStatOK, the host should not pass the pen motion to any other interactive object it may own that shares the same view.
Return
• kOfxStatOK, the action was trapped and the host should not pass the event to other objects it may own
• kOfxStatReplyDefault, the action was not trapped and the host can deal with it if it wants Parameters
• handle: handle to an interact instance, cast to anOfxInteractHandle
• inArgs: has the following properties on an image effect plugin,
– kOfxPropEffectInstancea handle to the effect for which the interact has been,
– kOfxInteractPropPixelScalethe scale factor to convert cannonical pixels to screen pixels – kOfxInteractPropBackgroundColourthe background colour of the application behind the current
view
– kOfxPropTimethe effect time at which changed occured
– kOfxImageEffectPropRenderScalethe render scale applied to any image fetched – kOfxInteractPropPenPositionposition of the pen in
– kOfxInteractPropPenViewportPositionposition of the pen in – kOfxInteractPropPenPressurethe pressure of the pen
• outArgs: is redundant and is set to NULL 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.
Pre
• kOfxActionCreateInstancehas been called on the instance handle,
• the current instance handle has hadkOfxInteractActionGainFocuscalled on it Post
• if the instance returnskOfxStatOK, the host should not pass the pen motion to any other interactive object it may own that shares the same focus.
Return
• kOfxStatOK , the action was trapped and the host should not pass the event to other objects it may own
• kOfxStatReplyDefault, the action was not trapped and the host can deal with it if it wants Parameters
• handle: handle to an interact instance, cast to anOfxInteractHandle
• inArgs: has the following properties on an image effect plugin
– kOfxPropEffectInstancea handle to the effect for which the interact has been,
– kOfxPropKeySymsingle integer value representing the key that was manipulated, this may not have a UTF8 representation (eg: a return key)
– kOfxPropKeyStringUTF8 string representing a character key that was pressed, some keys have no UTF8 encoding, in which case this is “”
– kOfxPropTimethe effect time at which changed occured
– kOfxImageEffectPropRenderScalethe render scale applied to any image fetched
• outArgs: is redundant and is set to NULL 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.
Pre
• kOfxActionCreateInstancehas been called on the instance handle,
• the current instance handle has hadkOfxInteractActionGainFocuscalled on it Post
• if the instance returnskOfxStatOK, the host should not pass the pen motion to any other interactive object it may own that shares the same focus.
Return
• kOfxStatOK , the action was trapped and the host should not pass the event to other objects it may own
• kOfxStatReplyDefault, the action was not trapped and the host can deal with it if it wants Parameters
• handle: handle to an interact instance, cast to anOfxInteractHandle
• inArgs: has the following properties on an image effect plugin
– kOfxPropEffectInstancea handle to the effect for which the interact has been,
– kOfxPropKeySymsingle integer value representing the key that was manipulated, this may not have a UTF8 representation (eg: a return key)
– kOfxPropKeyStringUTF8 string representing a character key that was pressed, some keys have no UTF8 encoding, in which case this is “”
– kOfxPropTimethe effect time at which changed occured
– kOfxImageEffectPropRenderScalethe render scale applied to any image fetched
• outArgs: is redundant and is set to NULL kOfxInteractActionKeyRepeat
This action is issued when a key on the keyboard is repeated. No openGL calls should be issued by the plug-in during this action.
Pre
• kOfxActionCreateInstancehas been called on the instance handle,
• the current instance handle has hadkOfxInteractActionGainFocuscalled on it Post
• if the instance returnskOfxStatOK, the host should not pass the pen motion to any other interactive object it may own that shares the same focus.
Return
• kOfxStatOK , the action was trapped and the host should not pass the event to other objects it may own
• kOfxStatReplyDefault, the action was not trapped and the host can deal with it if it wants Parameters
• handle: handle to an interact instance, cast to anOfxInteractHandle
• inArgs: has the following properties on an image effect plugin
– kOfxPropEffectInstancea handle to the effect for which the interact has been,
– kOfxPropKeySymsingle integer value representing the key that was manipulated, this may not have a UTF8 representation (eg: a return key)
– kOfxPropKeyStringUTF8 string representing a character key that was pressed, some keys have no UTF8 encoding, in which case this is “”
– kOfxPropTimethe effect time at which changed occured
– kOfxImageEffectPropRenderScalethe render scale applied to any image fetched
• outArgs: is redundant and is set to NULL kOfxInteractActionGainFocus
This action is issued when an interact gains input focus. No openGL calls should be issued by the plug-in during this action.
Pre
• kOfxActionCreateInstancehas been called on the instance handle, Return
• kOfxStatOKthe action was trapped
• kOfxStatReplyDefaultthe action was not trapped Parameters
• handle: handle to an interact instance, cast to anOfxInteractHandle
• inArgs: has the following properties on an image effect plugin
– kOfxPropEffectInstancea handle to the effect for which the interact is being used on, – kOfxInteractPropPixelScalethe scale factor to convert cannonical pixels to screen pixels, – kOfxInteractPropBackgroundColourthe background colour of the application behind the current
view
– kOfxPropTimethe effect time at which changed occured
– kOfxImageEffectPropRenderScalethe render scale applied to any image fetched
• outArgs: is redundant and is set to NULL kOfxInteractActionLoseFocus
This action is issued when an interact loses input focus. No openGL calls should be issued by the plug-in during this action.
Pre
• kOfxActionCreateInstancehas been called on the instance handle, Return
• kOfxStatOKthe action was trapped
• kOfxStatReplyDefaultthe action was not trapped Parameters
• handle: handle to an interact instance, cast to anOfxInteractHandle
• inArgs: has the following properties on an image effect plugin
– kOfxPropEffectInstancea handle to the effect for which the interact is being used on, – kOfxInteractPropPixelScalethe scale factor to convert cannonical pixels to screen pixels, – kOfxInteractPropBackgroundColourthe background colour of the application behind the current
view
– kOfxPropTimethe effect time at which changed occured
– kOfxImageEffectPropRenderScalethe render scale applied to any image fetched
• outArgs: is redundant and is set to NULL