Interacts
When a host presents a graphical user interface to an image effect, it may optionally give it the chance to draw its own custom GUI tools and to be able to interact with pen and keyboard input. In OFX this is done via the OfxInteract suite, which is found in the file ofxInteract.h.
OFX interacts by default use openGL to perform all drawing in
interacts, due to its portabilty, robustness and wide implementation.
As of 2022, some systems are moving away from OpenGL support in favor
of more modern graphics drawing APIs. So as of OFX 1.5, effects may
use the OfxDrawSuiteV1
instead of OpenGL if the host supports it.
Each object that can have their own interact a pointer property in it which should point to a separate main entry point. This entry point is not the same as the one in the OfxPlugin struct, as it needs to respond to a different set of actions to the effect.
There are two things in an image effect can have their own interact, these are…
as on overlay on the image being currently viewed in any image viewer, set via the effect descriptor’s
kOfxImageEffectPluginPropOverlayInteractV1
propertyas a replacement for any parameter’s standard GUI object, set this via the parameter descriptor’s
kOfxParamPropInteractV1
property.
Hosts might not be able to support interacts, to indicate this, two properties exist on the host descriptor which an effect should examine at description time so as to determine its own behaviour. These are…
Interacts are separate objects to the effect they are associated with, they have their own descriptor and instance handles passed into their separate main entry point.
An interact instance cannot exist without a plugin instance, an interact’s instance, once created, is bound to a single instance of a plugin until the interact instance is destroyed.
All interacts of the same type share openGL display lists, even if they are in different openGL contexts.
All interacts of the same type will have the same pixel types (this is a side effect of the last point), this will always be double buffered with at least RGB components. Alpha and the exact bit depth is left to the implementation.
So for example, all image effect overlays share the same display lists and have the same pixel depth, and all custom parameter GUIs share the same display list and have the same pixel depth, but overlays and custom parameter GUIs do not necassarily share the same display list/pixel depths.
An interact instance may be used in more than one view. Consider an image effect overlay interact in a host that supports multiple viewers to an effect instance. The same interact instance will be used in all views, the relevant properties controlling the view being changed before any action is passed to the interact. In this example, the draw action would be called once for each view open on the instance, with the projection, viewport and pixel scale being set appropriately for the view before each action.
Overlay Interacts
Hosts will generally display images (both input and output) in user
their interfaces. A plugin can put an interact in this display by
setting the effect descriptor
kOfxImageEffectPluginPropOverlayInteractV1
property to point to a main entry.
The viewport for such interacts will depend completely on the host.
The GL_PROJECTION
matrix will be set up so that it maps openGL
coordinates to canonical image coordinates.
The GL_MODELVIEW
matrix will be the identity matrix.
An overlay’s interact draw action should assume that it is sharing the openGL context and viewport with other objects that belong to the host. It should not blank the background and it should never swap buffers, that is for the host to do.
Parameter Interacts
All parameters, except for custom parameters, have some default
interface that the host creates for them. Be it a numeric slider, colour
swatch etc… Effects can override the default interface (or set an
interface for a custom parameter) by setting the
kOfxParamPropInteractV1
. This will
completely replace the parameters default user interface in the ‘paged’
and hierarchical interfaces, but it will not replace the parameter’s
interface in any animation sheet.
Properties affecting custom interacts for parameters are…
The viewport for such interacts will be dependent upon the various properties above, and possibly a per host override in any XML resource file.
The GL_PROJECTION
matrix will be an orthographic 2D view with -0.5,-0.5
at the bottom left and viewport width-0.5, viewport height-0.5 at the
top right.
The GL_MODELVIEW
matrix will be the identity matrix.
The bit depth will be double buffered 24 bit RGB.
A parameter’s interact draw function will have full responsibility for drawing the interact, including clearing the background and swapping buffers.
Interact Actions
The following actions are passed to any interact entry point in an image effect plug-in.
The Generic Describe Action called to describe the specific interact ,
The Create Instance Action called just after an instance of the interact is created,
The Generic Destroy Instance Action called just before of the interact is destroyed,
The Draw Action called to have the interact draw itself,
kOfxInteractActionPenMotion
called whenever the interact has the input focus and the pen has moved, regardless of whether the pen is up or down,kOfxInteractActionPenDown
called whenever the interact has the input focus and the pen has changed state to ‘down’,kOfxInteractActionPenUp
called whenever the interact has the input focus and the pen has changed state to ‘up,kOfxInteractActionKeyDown
called whenever the interact has the input focus and a key has gone down,kOfxInteractActionKeyUp
called whenever the interact has the input focus and a key has gone up,kOfxInteractActionKeyRepeat
called whenever the interact has the input focus and a key has gone down and a repeat key sequence has been sent,kOfxInteractActionGainFocus
called whenever the interact gains input focus,kOfxInteractActionLoseFocus
called whenever the interact loses input focus,
An interact cannot be described until an effect has been described.
An interact instance must always be associated with an effect instance. So it gets created after an effect and destroyed before one.
An interact instance should be issued a gain focus action before any key or pen actions are issued, and a lose focus action when it goes.