Changes to the API for 1.2

Introduction

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.

Packaging

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.

Versioning

Three new properties are provided to identify and version a plugin and/or host. These are…

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. kOfxPropVersion provides a way to do that.

Plugin Description

The new property kOfxPropPluginDescription 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 property 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, kOfxPropParamSetNeedsSyncing. This 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.

Sequential Rendering

Flagging sequential rendering has been slightly modified. The kOfxImageEffectInstancePropSequentialRender property has had a third allowed state added, which indicate that a plugin would prefer to be sequentially rendered if possible, but need not be.

The kOfxImageEffectInstancePropSequentialRender property has also been added to the host descriptor, to indicate whether the host can support sequential rendering.

The new property kOfxImageEffectPropSequentialRenderStatus 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 kOfxImageEffectPropInteractiveRenderStatus

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 kOfxPropHostOSHandle

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….

These new parameter types can set their defaults in one of two coordinate systems, the property kOfxParamPropDefaultCoordinateSystem 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 kOfxInteractPropSuggestedColour property.

Interact Viewport Pen Position

The new property kOfxInteractPropPenViewportPosition 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 actions that kOfxInteractPropPenPosition is passed to.

Parametric Parameters

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.