File ofxInteract.h
Contains the API for ofx plugin defined GUIs and interaction.
Defines
-
kOfxInteractSuite
-
kOfxInteractPropSlaveToParam
The set of parameters on which a value change will trigger a redraw for an interact.
Type - string X N
Property Set - interact instance property (read/write)
Default - no values set
Valid Values - the name of any parameter associated with this interact.
If the interact is representing the state of some set of OFX parameters, then is will need to be redrawn if any of those parameters’ values change. This multi-dimensional property links such parameters to the interact.
The interact can be slaved to multiple parameters (setting index 0, then index 1 etc…)
-
kOfxInteractPropPixelScale
The size of a real screen pixel under the interact’s canonical projection.
Type - double X 2
Property Set - interact instance and actions (read only)
-
kOfxInteractPropBackgroundColour
The background colour of the application behind an interact instance.
Type - double X 3
Property Set - read only on the interact instance and in argument to the kOfxInteractActionDraw action
Valid Values - from 0 to 1
The components are in the order red, green then blue.
-
kOfxInteractPropSuggestedColour
The suggested colour to draw a widget in an interact, typically for overlays.
Type - double X 3
Property Set - read only on the interact instance
Default - 1.0
Valid Values - greater than or equal to 0.0
Some applications allow the user to specify colours of any overlay via a colour picker, this property represents the value of that colour. Plugins are at liberty to use this or not when they draw an overlay.
If a host does not support such a colour, it should return kOfxStatReplyDefault
-
kOfxInteractPropPenPosition
The position of the pen in an interact.
Type - double X 2
Property Set - read only in argument to the kOfxInteractActionPenMotion, kOfxInteractActionPenDown and kOfxInteractActionPenUp actions
This value passes the postion of the pen into an interact. This is in the interact’s canonical coordinates.
-
kOfxInteractPropPenViewportPosition
The position of the pen in an interact in viewport coordinates.
Type - int X 2
Property Set - read only in argument to the kOfxInteractActionPenMotion, kOfxInteractActionPenDown and kOfxInteractActionPenUp actions
This value passes the postion of the pen into an interact. This is in the interact’s openGL viewport coordinates, with 0,0 being at the bottom left.
-
kOfxInteractPropPenPressure
The pressure of the pen in an interact.
Type - double X 1
Property Set - read only in argument to the kOfxInteractActionPenMotion, kOfxInteractActionPenDown and kOfxInteractActionPenUp actions
Valid Values - from 0 (no pressure) to 1 (maximum pressure)
This is used to indicate the status of the ‘pen’ in an interact. If a pen has only two states (eg: a mouse button), these should map to 0.0 and 1.0.
-
kOfxInteractPropBitDepth
Indicates whether the dits per component in the interact’s openGL frame buffer.
Type - int X 1
Property Set - interact instance and descriptor (read only)
-
kOfxInteractPropHasAlpha
Indicates whether the interact’s frame buffer has an alpha component or not.
Type - int X 1
Property Set - interact instance and descriptor (read only)
Valid Values - This must be one of
0 indicates no alpha component
1 indicates an alpha component
-
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.
- Parameters:
handle – handle to the interact descriptor, cast to an OfxInteractHandle
inArgs – is redundant and is set to NULL
outArgs – is redundant and is set to NULL
- Pre:
The plugin has been loaded and the effect described.
- Returns:
kOfxStatOK the action was trapped and all was well
kOfxStatErrMemory in which case describe may be called again after a memory purge
kOfxStatFailed something was wrong, the host should ignore the interact
-
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.
- Parameters:
handle – handle to the interact instance, cast to an OfxInteractHandle
inArgs – is redundant and is set to NULL
outArgs – is redundant and is set to NULL
- Pre:
kOfxActionDescribe has been called on this interact
- 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
kOfxStatErrMemory in which case this may be called again after a memory purge
kOfxStatFailed in which case the host should ignore this interact
-
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.
- Parameters:
handle – handle to the interact instance, cast to an OfxInteractHandle
inArgs – is redundant and is set to NULL
outArgs – is redundant and is set to NULL
- Pre:
kOfxActionCreateInstance has 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
- 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
kOfxStatOK the action was trapped and all was well
kOfxStatReplyDefault the action was ignored as the effect had nothing to do
kOfxStatFailed something went wrong, but no error code appropriate.
-
kOfxInteractActionDraw
This action is issued to an interact whenever the host needs the plugin to redraw the given interact.
The interact should either issue OpenGL calls to draw itself, or use DrawSuite calls.
If this is called via kOfxImageEffectPluginPropOverlayInteractV2, drawing MUST use DrawSuite.
If this is called via kOfxImageEffectPluginPropOverlayInteractV1, drawing SHOULD use OpenGL. Some existing plugins may use DrawSuite via kOfxImageEffectPluginPropOverlayInteractV1 if it’s supported by the host, but this is discouraged.
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.
- Parameters:
handle – handle to an interact instance, cast to an OfxInteractHandle
inArgs – has the following properties on an image effect plugin
kOfxPropEffectInstance a handle to the effect for which the interact has been,
kOfxInteractPropPixelScale the scale factor to convert cannonical pixels to screen pixels
kOfxInteractPropBackgroundColour the background colour of the application behind the current view
kOfxPropTime the effect time at which changed occured
kOfxImageEffectPropRenderScale the render scale applied to any image fetched
outArgs – is redundant and is set to NULL
- Pre:
kOfxActionCreateInstance has 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
- Returns:
kOfxStatOK the action was trapped and all was well
kOfxStatReplyDefault the action was ignored
kOfxStatFailed something went wrong, the host should ignore this interact in future
-
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.
- Parameters:
handle – handle to an interact instance, cast to an OfxInteractHandle
inArgs – has the following properties on an image effect plugin
kOfxPropEffectInstance a handle to the effect for which the interact has been,
kOfxInteractPropPixelScale the scale factor to convert cannonical pixels to screen pixels
kOfxInteractPropBackgroundColour the background colour of the application behind the current view
kOfxPropTime the effect time at which changed occured
kOfxImageEffectPropRenderScale the render scale applied to any image fetched
kOfxInteractPropPenPosition postion of the pen in,
kOfxInteractPropPenViewportPosition position of the pen in,
kOfxInteractPropPenPressure the pressure of the pen,
outArgs – is redundant and is set to NULL
- Pre:
kOfxActionCreateInstance has been called on the instance handle
the current instance handle has had kOfxInteractActionGainFocus called on it
- Post:
if the instance returns kOfxStatOK the host should not pass the pen motion to any other interactive object it may own that shares the same view.
- Returns:
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
-
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.
- Parameters:
handle – handle to an interact instance, cast to an OfxInteractHandle
inArgs – has the following properties on an image effect plugin,
kOfxPropEffectInstance a handle to the effect for which the interact has been,
kOfxInteractPropPixelScale the scale factor to convert cannonical pixels to screen pixels
kOfxInteractPropBackgroundColour the background colour of the application behind the current view
kOfxPropTime the effect time at which changed occured
kOfxImageEffectPropRenderScale the render scale applied to any image fetched
kOfxInteractPropPenPosition position of the pen in
kOfxInteractPropPenViewportPosition position of the pen in
kOfxInteractPropPenPressure the pressure of the pen
outArgs – is redundant and is set to NULL
- Pre:
kOfxActionCreateInstance has been called on the instance handle,
the current instance handle has had kOfxInteractActionGainFocus called on it
- Post:
if the instance returns kOfxStatOK, the host should not pass the pen motion to any other interactive object it may own that shares the same view.
- Returns:
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
-
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.
- Parameters:
handle – handle to an interact instance, cast to an OfxInteractHandle
inArgs – has the following properties on an image effect plugin,
kOfxPropEffectInstance a handle to the effect for which the interact has been,
kOfxInteractPropPixelScale the scale factor to convert cannonical pixels to screen pixels
kOfxInteractPropBackgroundColour the background colour of the application behind the current view
kOfxPropTime the effect time at which changed occured
kOfxImageEffectPropRenderScale the render scale applied to any image fetched
kOfxInteractPropPenPosition position of the pen in
kOfxInteractPropPenViewportPosition position of the pen in
kOfxInteractPropPenPressure the pressure of the pen
outArgs – is redundant and is set to NULL
- Pre:
kOfxActionCreateInstance has been called on the instance handle,
the current instance handle has had kOfxInteractActionGainFocus called on it
- Post:
if the instance returns kOfxStatOK, the host should not pass the pen motion to any other interactive object it may own that shares the same view.
- Returns:
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
-
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.
- Parameters:
handle – handle to an interact instance, cast to an OfxInteractHandle
inArgs – has the following properties on an image effect plugin
kOfxPropEffectInstance a handle to the effect for which the interact has been,
kOfxPropKeySym single integer value representing the key that was manipulated, this may not have a UTF8 representation (eg: a return key)
kOfxPropKeyString UTF8 string representing a character key that was pressed, some keys have no UTF8 encoding, in which case this is “”
kOfxPropTime the effect time at which changed occured
kOfxImageEffectPropRenderScale the render scale applied to any image fetched
outArgs – is redundant and is set to NULL
- Pre:
kOfxActionCreateInstance has been called on the instance handle,
the current instance handle has had kOfxInteractActionGainFocus called on it
- Post:
if the instance returns kOfxStatOK, the host should not pass the pen motion to any other interactive object it may own that shares the same focus.
- Returns:
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
-
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.
- Parameters:
handle – handle to an interact instance, cast to an OfxInteractHandle
inArgs – has the following properties on an image effect plugin
kOfxPropEffectInstance a handle to the effect for which the interact has been,
kOfxPropKeySym single integer value representing the key that was manipulated, this may not have a UTF8 representation (eg: a return key)
kOfxPropKeyString UTF8 string representing a character key that was pressed, some keys have no UTF8 encoding, in which case this is “”
kOfxPropTime the effect time at which changed occured
kOfxImageEffectPropRenderScale the render scale applied to any image fetched
outArgs – is redundant and is set to NULL
- Pre:
kOfxActionCreateInstance has been called on the instance handle,
the current instance handle has had kOfxInteractActionGainFocus called on it
- Post:
if the instance returns kOfxStatOK, the host should not pass the pen motion to any other interactive object it may own that shares the same focus.
- Returns:
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
-
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.
- Parameters:
handle – handle to an interact instance, cast to an OfxInteractHandle
inArgs – has the following properties on an image effect plugin
kOfxPropEffectInstance a handle to the effect for which the interact has been,
kOfxPropKeySym single integer value representing the key that was manipulated, this may not have a UTF8 representation (eg: a return key)
kOfxPropKeyString UTF8 string representing a character key that was pressed, some keys have no UTF8 encoding, in which case this is “”
kOfxPropTime the effect time at which changed occured
kOfxImageEffectPropRenderScale the render scale applied to any image fetched
outArgs – is redundant and is set to NULL
- Pre:
kOfxActionCreateInstance has been called on the instance handle,
the current instance handle has had kOfxInteractActionGainFocus called on it
- Post:
if the instance returns kOfxStatOK, the host should not pass the pen motion to any other interactive object it may own that shares the same focus.
- Returns:
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
-
kOfxInteractActionGainFocus
This action is issued when an interact gains input focus. No openGL calls should be issued by the plug-in during this action.
- Parameters:
handle – handle to an interact instance, cast to an OfxInteractHandle
inArgs – has the following properties on an image effect plugin
kOfxPropEffectInstance a handle to the effect for which the interact is being used on,
kOfxInteractPropPixelScale the scale factor to convert cannonical pixels to screen pixels,
kOfxInteractPropBackgroundColour the background colour of the application behind the current view
kOfxPropTime the effect time at which changed occured
kOfxImageEffectPropRenderScale the render scale applied to any image fetched
outArgs – is redundant and is set to NULL
- Pre:
kOfxActionCreateInstance has been called on the instance handle,
- Returns:
kOfxStatOK the action was trapped
kOfxStatReplyDefault the action was not trapped
-
kOfxInteractActionLoseFocus
This action is issued when an interact loses input focus. No openGL calls should be issued by the plug-in during this action.
- Parameters:
handle – handle to an interact instance, cast to an OfxInteractHandle
inArgs – has the following properties on an image effect plugin
kOfxPropEffectInstance a handle to the effect for which the interact is being used on,
kOfxInteractPropPixelScale the scale factor to convert cannonical pixels to screen pixels,
kOfxInteractPropBackgroundColour the background colour of the application behind the current view
kOfxPropTime the effect time at which changed occured
kOfxImageEffectPropRenderScale the render scale applied to any image fetched
outArgs – is redundant and is set to NULL
- Pre:
kOfxActionCreateInstance has been called on the instance handle,
- Returns:
kOfxStatOK the action was trapped
kOfxStatReplyDefault the action was not trapped
Typedefs
-
typedef struct OfxInteract *OfxInteractHandle
Blind declaration of an OFX interactive gui.
-
typedef struct OfxInteractSuiteV1 OfxInteractSuiteV1
OFX suite that allows an effect to interact with an openGL window so as to provide custom interfaces.
-
struct OfxInteractSuiteV1
- #include <ofxInteract.h>
OFX suite that allows an effect to interact with an openGL window so as to provide custom interfaces.
Public Members
-
OfxStatus (*interactSwapBuffers)(OfxInteractHandle interactInstance)
Requests an openGL buffer swap on the interact instance.
-
OfxStatus (*interactRedraw)(OfxInteractHandle interactInstance)
Requests a redraw of the interact instance.
-
OfxStatus (*interactGetPropertySet)(OfxInteractHandle interactInstance, OfxPropertySetHandle *property)
Gets the property set handle for this interact handle.
-
OfxStatus (*interactSwapBuffers)(OfxInteractHandle interactInstance)