Changes to the API for 1.2
This chapter lists the changes and extensions between the 1.1 version of the API and the 1.2 version of the API. The extension are backwards compatible, so that a 1.2 plugin will run on an earlier version of a host, provided a bit of care is taken. A 1.2 host will easily support a plugin written to an earlier API.
A new architecture directory was added to the bundle hierarchy to specifically contain Mac OSX 64 bit builds. The current ‘MacOS’ architecture is a fall back for 32 bit only and/or universal binary builds.
Three new properties are provided to identify and version a plugin and/or host. These are…
kOfxPropAPIVersiona multi-dimensional integer that specifies the version of the API being implemented by a host.
kOfxPropVersiona multi-dimensional integer that provides a version number for host and plugin
kOfxPropVersionLabela user readable version label
Before 1.2 there was no way to identify the version of a host
application, which a plugin could use to work around known bugs and
problems in known versions.
provides a way to do that.
The new property
allows a plugin to set a string which provides a description to a user.
Parameter Groups and Icons
Group parameters are typically displayed in a hierarchical manner on
many applications, with ‘twirlies’ to open and close the group. The new
kOfxParamPropGroupOpen is used to
specify if a group parameter should be initially open or closed.
Some applications are able to display icons instead of text when
labelling parameters. The new property,
kOfxPropIcon, specifies an SVG file and/or a PNG
file to use as an icon in such host applications.
New Message Suite
A new message suite has been specified,
OfxMessageSuiteV2, this adds two new functions.
One to set a persistent message on an effect, and a second to clear that
message. This would typically be used to flag an error on an effects.
New Syncing Property
A new property has been added to parameter sets,
is used by plugins with internal data structures that need syncing back
to parameters for persistence and so on. This property should be set
whenever the plugin changes it’s internal state to inform the host that
a sync will be required before the next serialisation of the plugin.
Without this property, the host would have to continually force the
plugin to sync it’s private data, whether that was a redundant operation
or not. For large data sets, this can be a significant overhead.
Flagging sequential rendering has been slightly modified. The
property has had a third allowed state added, which indicate that a
plugin would prefer to be sequentially rendered if possible, but need
property has also been added to the host descriptor, to indicate whether
the host can support sequential rendering.
The new property
is now passed to the render actions to indicate that a host is currently
sequentially rendering or not.
Interactive Render Notification
A new property has been added to flag a render as being in response to
an interactive change by a user, as opposed to a batch render. This is
Host Operating System Handle
A new property has been added to allow a plugin to request the host
operating system specific application handle (ie: on Windows (tm) this
would be the application’s root hWnd). This is
Non Normalised Spatial Parameters
Normalised double parameters have proved to be more of a problem than expected. The major idea was to provide resolution independence for spatial parameters. However, in practice, having to specify parameters as a fraction of a yet to be determined resolution is problematic. For example, if you want to set something to be explicitly ‘20’, there is no way of doing that. The main problem stems from normalised params conflating two separate issues, flagging to the host that a parameter was spatial, and being able to specify defaults in a normalised co-ordinate system.
With 1.2 new spatial double parameter types are defined. These have their values manipulated in canonical coordinates, however, they have an option to specify their default values in a normalise coordinate system. These are….
These new double parameter types are….
kOfxParamDoubleTypeX- a size in the X dimension dimension (1D only), new for 1.2
kOfxParamDoubleTypeXAbsolute- a position in the X dimension (1D only), new for 1.2
kOfxParamDoubleTypeY- a size in the Y dimension dimension (1D only), new for 1.2
kOfxParamDoubleTypeYAbsolute- a position in the X dimension (1D only), new for 1.2
kOfxParamDoubleTypeXY- a size in the X and Y dimension (2D only), new for 1.2
kOfxParamDoubleTypeXYAbsolute- a position in the X and Y dimension (2D only), new for 1.2
These new parameter types can set their defaults in one of two
coordinate systems, the property
Specifies the coordinate system the default value is being specified in.
Plugins can check
kOfxPropAPIVersion to see if
these new parameter types are supported
Native Overlay Handles
Some applications have their own overlay handles for certain types of parameter (eg: spatial positions). It is often better to rely on those, than have a plugin implement their own overlay handles. Two new parameter, properties are available to do that, one used by the host to indicate if such handles are available. The other by a plugin telling the host to use such handle.
Interact Colour Hint
Some applications allow the user to specify colours of any overlay via a
colour picker. Plug-ins can access this via the
Interact Viewport Pen Position
The new property
is used to pass a pen position in viewport coordinate, rather than a
connaonical. This is sometimes much more convenient. It is passed to all
kOfxInteractPropPenPosition is passed to.
A new optional parameter type, and supporting suite, is introduced, parametric parameters. This allows for the construction of user defined lookup tables and so on.