The image effect API uses a variety of different objects. Some are defined via blind data handles, others via property sets, and some by a combination of the two. These objects are...
The host descriptor is represented by the properties found on the
host
property set handle in the
OfxHost struct
. The complete set of read only properties are found in the section
Properties on the Image Effect Host
.
These sets of properties are there to describe the capabilities of the host to a plug-in, thus giving a plug-in the ability to modify its behaviour depending on the capabilities of the host.
A host descriptor is valid while a plug-in is loaded.
An effect is an object in the OFX Image Effect API that represents an image processing plug-in. It has associated with it a set of properties, a set of image clips and a set of parameters. These component objects of an effect are defined and used by an effect to do whatever processing it needs to. A handle to an image effect (instance or descriptor) is passed into a plug-in's
main entry point
handle
argument.
The functions that directly manipulate an image effect handle are specified in the
image effect suite
found in the header file
ofxImageEffect.h
.
An effect descriptor is an object of type
OfxImageEffectHandle
passed into an effect's
main
entry point
handle
argument. The two actions it is passed to are...
A effect descriptor does not refer to a 'live' effect, it is a handle which the effect uses to describe itself back to the host. It does this by setting a variety of properties on an associated property handle, and specifying a variety of objects (such as clips and parameters) using functions in the available suites.
Once described, a host should cache away the description in some manner so that when an instance is made, it simply looks at the description and creates the necessary objects needed by that instance. This stops the overhead of having every instance be forced to describe itself over the API.
Effect descriptors are only valid in a effect for the duration of the instance they were passed into.
The properties on an effect descriptor can be found in the section Properties on an Effect Descriptor .
A effect instance is an object of type
OfxImageEffectHandle
passed into an effect's
main entry point
handle
argument. The
handle
argument should be statically cast to this type. It is passed into all actions of an image effect that a descriptor is not passed into.
The effect instance represents a 'live' instance of an effect. Because an effect has previously been described, via a effect descriptor, an instance does not have to respecify the parameters, clips and properties that it needs. These means, that when an instance is passed to an effect, all the objects previously described will have been created.
Generally multiple instances of an effect can be in existence at the same time, each with a different set of parameters, clips and properties.
Effect instances are valid between the calls to
kOfxActionCreateInstance
and
kOfxActionDestroyInstance
, for which it is passed as the
handle
argument.
The properties on an effect instance can be found in the section Properties on an Effect Instance .
A clip is a sequential set of images attached to an effect. They are used to fetch images from a host and to specify how a plug-in wishes to manage the sequence.
Clip descriptors are returned by the
OfxImageEffectSuiteV1::clipDefine
function. They are used during the kOfxActionDescribe action by an effect to indicate the presence of an input or output clip and how that clip behaves.
A clip descriptor is only valid for the duration of the action it was created in.
The properties on a clip descriptor can be found in the section Properties on a Clip Descriptor .
Clip instances are returned by the
OfxImageEffectSuiteV1::clipGetHandle
function. They are are used to access images and and manipulate properties on an effect instance's input and output clips. A variety of functions in the
OfxImageEffectSuiteV1
are used to manipulate them.
A clip instance is valid while the related effect instance is valid.
The properties on a clip instance can be found in the section Properties on a Clip Instance .
Parameters are user visible objects that an effect uses to specify its state, for example a floating point value used to control the blur size in a blur effect. Parameters (both descriptors and instances) are represented as blind data handles of type
OfxParamHandle
.
Parameter sets are the collection of parameters that an effect has associated with it. They are represented by the type
OfxParamSetHandle
. The contents of an effect's parameter set are defined during the
kOfxImageEffectActionDescribeInContext
action. Parameters cannot be dynamically added to, or deleted from an effect instance.
Parameters can be of a wide range of types, each of which have their own unique capabilities and property sets. For example a colour parameter differs from a boolean parameter.
Parameters and parameter sets are manipulated via the calls and properties in the
parameter suite
specified in
ofxParam.h
header file. The properties on parameter instances and descriptors can be found in the section
Properties on Parameter Descriptors and Instances
.
Parameter set descriptors are returned by the
OfxImageEffectSuiteV1::getParamSet
function. This returns a handle associated with an image effect descriptor which can be used by the parameter suite routines to create and describe parameters to a host.
A parameter set descriptor is valid for the duration of the
kOfxImageEffectActionDescribeInContext
action in which it is fetched.
Parameter descriptors are returned by the
OfxParameterSuiteV1::paramDefine
function. They are used to define the existence of a parameter to the host, and to set the various attributes of that parameter. Later, when an effect instance is created, an instance of the described parameter will also be created.
A parameter descriptor is valid for the duration of the
kOfxImageEffectActionDescribeInContext
action in which it is created.
Parameter set instances are returned by the
OfxImageEffectSuiteV1::getParamSet
function. This returns a handle associated with an image effect instance which can be used by the parameter suite routines to fetch and describe parameters to a host.
A parameter set handle instance is valid while the associated effect instance remains valid.
Parameter instances are returned by the
OfxParameterSuiteV1::paramGetHandle
function. This function fetches a previously described parameter back from the parameter set. The handle can then be passed back to the various functions in the
OfxParameterSuite1V
to manipulate it.
A parameter instance handle remains valid while the associated effect instance remains valid.
An image instance is an object returned by the
OfxImageEffectSuiteV1::clipGetImage
function. This fetches an image out of a clip and returns it as a property set to the plugin. The image can be accessed by looking up the property values in that set, which includes the data pointer to the image.
An image instance is valid until the effect calls
OfxImageEffectSuiteV1::clipReleaseImage
on the property handle. The effect
must
release all fetched images before it returns from the action.
The set of properties that make up an image can be found in the section Properties on an Image .
An interact is an OFX object that is used to draw custom user interface elements, for example overlays on top of a host's image viewer or custom parameter widgets. Interacts have their own
main entry point
, which is separate to the effect's main entry point. Typically an interact's main entry point is specified as a pointer property on an OFX object, for example the
kOfxImageEffectPluginPropOverlayInteractV1
property on an effect descriptor.
The functions that directly manipulate interacts are in the
interact suite
found in the header file
ofxInteract.h
, as well as the properties and specific actions that apply to interacts.
Interact descriptors are blind handles passed to the
describe action
sent to an interact's separate main entry point. They should be cast to the type
OfxInteractHandle
.
The properties found on a descriptor are found in section Properties on Interact Descriptors .
Interact instances are blind handles passed to all actions but the
describe action
sent to an interact's separate main entry point. They should be cast to the type
OfxInteractHandle
.
The properties found on an instance are found in section Properties on Interact Instance .
