Effect Parameters

Introduction

Nearly all plug-ins have some sort of parameters that control their behaviour, the radius of a circle drawer, the frequencies to filter out of an audio signal, the colour of a lens flare and so on.

Seeing as hosts already provide for the general management of their own native parameters (eg: persistence, interface, animation etc…), it would make no sense to force plug-ins to do this all themselves.

The OFX Parameters Suite is the means by which parameters are defined and used by the plug-in but maintained by the host. It is defined in the ofxParam.h header file.

Note that the entire state of the plugin is encoded in the value of its parameter set. If you need to persist some sort of private data, you must do so by setting param values in the effects. The kOfxActionSyncPrivateData is an action that tells you when to flush any values that need persisting out to the effects param set. You can reconstruct your private data during the kOfxActionCreateInstance.

Defining Parameters

A plugin needs to define it’s parameters during a describe action. It does this with the OfxParameterSuiteV1::paramDefine() function, which returns a handle to a parameter description. Parameters cannot currently be defined outside of the plugins describe actions.

Parameters are uniquely labelled within a plugin with an ASCII null terminated C-string. This name is not necassarily meant to be end-user readable, various properties are provided to set the user visible labels on the param.

All parameters hold properties, though the exact set of properties on a parameter is dependent on the type of the parameter.

A parameter’s handle comes in two slightly different flavours. The handle returned inside a plugin’s describe action is not an actual instance of a parameter, it is there for the purpose description only. You can only set properties on that handle (eg: label, min/max value, default …), you cannot get values from it or set values in it. The parameters defined in the describe action will common to all instances of a plugin.

The handle returned by OfxParameterSuiteV1::paramGetHandle() outside of a describe action will be a working instance of a parameter, you can still set (some) properties of the parameter, and all the get/set value functions are now usable.

Getting and Setting Parameter Values

During rendering and interactions, a plugin gets its param values via OfxParameterSuiteV1::paramGetValue() or OfxParameterSuiteV1::paramGetValueAtTime().

To set param values, a plugin can use OfxParameterSuiteV1::paramSetValue() or OfxParameterSuiteV1::paramSetValueAtTime().

In addition, OfxParameterSuiteV1 has functions for manipulating keyframes, copying and editing params, getting their properties, and getting derivatives and integrals of param values.

Parameter Types

There are eighteen types of parameter. These are

  • kOfxParamTypeInteger

    String to identify a param as a single valued integer.

  • kOfxParamTypeInteger2D

    String to identify a param as a Two dimensional integer point parameter.

  • kOfxParamTypeInteger3D

    String to identify a param as a Three dimensional integer parameter.

  • kOfxParamTypeDouble

    String to identify a param as a Single valued floating point parameter

  • kOfxParamTypeDouble2D

    String to identify a param as a Two dimensional floating point parameter.

  • kOfxParamTypeDouble3D

    String to identify a param as a Three dimensional floating point parameter.

  • kOfxParamTypeRGB

    String to identify a param as a Red, Green and Blue colour parameter.

  • kOfxParamTypeRGBA

    String to identify a param as a Red, Green, Blue and Alpha colour parameter.

  • kOfxParamTypeBoolean

    String to identify a param as a Single valued boolean parameter.

  • kOfxParamTypeChoice

    String to identify a param as a Single valued, ‘one-of-many’ parameter.

  • kOfxParamTypeStrChoice

    String to identify a param as a string-valued ‘one-of-many’ parameter.

    Since

    Version 1.5

  • kOfxParamTypeString

    String to identify a param as a String (UTF8) parameter.

  • kOfxParamTypeCustom

    String to identify a param as a Plug-in defined parameter.

  • kOfxParamTypePushButton

    String to identify a param as a PushButton parameter.

  • kOfxParamTypeGroup

    String to identify a param as a Grouping parameter.

  • kOfxParamTypePage

    String to identify a param as a page parameter.

  • kOfxParamTypeParametric

    String to identify a param as a single valued integer.

Multidimensional Parameters

Some parameter types are multi dimensional, these are…

These parameters are treated in an atomic manner, so that all dimensions are set/retrieved simultaneously. This applies to keyframes as well.

The non colour parameters have an implicit ‘X’, ‘Y’ and ‘Z’ dimension, and any interface should display them with such labels.

Integer Parameters

These are typed by kOfxParamTypeInteger, kOfxParamTypeInteger2D and kOfxParamTypeInteger3D.

Integer parameters are of 1, 2 and 3D varieties and contain integer values, between INT_MIN and INT_MAX.

Double Parameters

These are typed by kOfxParamTypeDouble, kOfxParamTypeDouble2D and kOfxParamTypeDouble3D.

Double parameters are of 1, 2 and 3D varieties and contain double precision floating point values.

Colour Parameters

These are typed by kOfxParamTypeRGB and kOfxParamTypeRGBA.

Colour parameters are 3 or 4 dimensional double precision floating point parameters. They are displayed using the host’s appropriate interface for a colour. Values are always normalised in the range [0 .. 1], with 0 being the nominal black point and 1 being the white point.

Boolean Parameters

This is typed by kOfxParamTypeBoolean.

Boolean parameters are integer values that can have only one of two values, 0 or 1.

Choice Parameters

This is typed by kOfxParamTypeChoice.

Choice parameters are integer values from 0 to N-1, which correspond to N labeled options, but see kOfxParamPropChoiceOrder and the section below this for how to change that.

Choice parameters have their individual options set via the kOfxParamPropChoiceOption property, for example

gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, 0, "1st Choice");
gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, 1, "2nd Choice");
gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, 2, "3nd Choice");
...
gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, n, "nth Choice");

It is an error to have gaps in the choices after the describe action has returned.

Note: plugins can change the text of options strings in new versions with no compatibility impact, since the host should only store the index. But they should not change the order of options without using kOfxParamPropChoiceOrder.

Setting Choice Param Order

As of OFX v1.5, plugins can optionally specify the order in which the host should display each choice option, using kOfxParamPropChoiceOrder.

This property contains a set of integers, of the same length as the options for the choice parameter. If the host supports this property, it should sort the options and the order list together, and display the options in increasing order.

This property is useful when changing order of choice param options, or adding new options in the middle, in a new version of the plugin.

// Plugin v1:
Option = {"OptA", "OptB", "OptC"}
Order  = {0, 1, 2} // default, or explicit

// Plugin v2:
// add NewOpt at the end of the list, but specify order so it comes one before the end in the UI
// Will display OptA / OptB / NewOpt / OptC
Option = {"OptA", "OptB", "OptC", "NewOpt"}
Order  = {0, 1, 3, 2} // or anything that sorts the same, e.g. {1, 100, 300, 200}

In this case if the user had selected “OptC” in v1, and then loaded the project in v2, “OptC” will still be selected even though it is now the 4th option, and the plugin will get the param value 2, as it did in its previous version.

The default, if unspecified, is ordinal integers starting from zero, so the options are displayed in their natural order.

Values may be arbitrary 32-bit integers. The same value must not occur more than once in the order list; behavior is undefined if the same value occurs twice in the list. Plugins should use non-negative values; some hosts may choose to hide options with negative Order values.

Note that kOfxParamPropChoiceOrder does not affect project storage or operation; it is only used by the host UI. This way it is 100% backward compatible; even if the plugin sets it and the host doesn’t support it, the plugin will still work as usual. Its options will just appear with the new ones at the end rather than the preferred order.

To query whether a host supports this, a plugin should attempt to set the property and check the return status. If the host does not support kOfxParamPropChoiceOrder, a plugin should not insert new values into the middle of the options list, nor reorder the options, in a new version, otherwise old projects will not load properly.

Note: this property does not help if a plugin wants to remove an option. One way to handle that case is to define a new choice param in v2 and hide the old v1 param, then use some custom logic to populate the v2 param appropriately.

Also in 1.5, see the new kOfxParamTypeStrChoice param type for another way to do this: the plugin specifies a set of string values as well as user-visible options, and the host stores the string value. Plugins can then change the UI order at will in new versions, by reordering the options and enum arrays.

Available since 1.5.

String-Valued Choice Parameters

This is typed by kOfxParamTypeStrChoice.

String Choice (“StrChoice”) parameters are string-valued, unlike standard Choice parameters. This way plugins may change the text and order of the choices in new versions as desired, without sacrificing compatibility. The host stores the string value rather than the index of the option, and when loading a project, finds and selects the option with the corresponding enum.

Choice parameters have their individual options and enums set via the kOfxParamPropChoiceOption and kOfxParamPropChoiceEnum properties, for example

gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, 0, "1st Choice");
gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, 1, "2nd Choice");
gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, 2, "3nd Choice");
...
// enums: string values to be returned as param value, and stored by the host in the project
gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceEnum, 0, "choice-1");
gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceEnum, 1, "choice-2");
gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceEnum, 2, "choice-3");

The default value of a StrChoice param must be one of the specified enums, or the behavior is undefined.

It is an error to have gaps in the choices after the describe action has returned. The Option and Enum arrays must be of the same length, otherwise the behavior is undefined.

If a plugin removes enums in later versions and a project is saved with the removed enum, behavior is undefined, but it is recommended that the host use the default value in that case.

To check for availability of this param type, a plugin may check the host property kOfxParamHostPropSupportsStrChoice.

StrChoice parameters may also be reordered using kOfxParamPropChoiceOrder; see the previous section.

Available since 1.5.

String Parameters

This is typed by kOfxParamTypeString.

String parameters contain null terminated char * UTF8 C strings. They can be of several different variants, which is controlled by the kOfxParamPropStringMode property, these are

  • kOfxParamStringIsSingleLine

    Used to set a string parameter to be single line, value to be passed to a kOfxParamPropStringMode property.

  • kOfxParamStringIsMultiLine

    Used to set a string parameter to be multiple line, value to be passed to a kOfxParamPropStringMode property.

  • kOfxParamStringIsFilePath

    Used to set a string parameter to be a file path, value to be passed to a kOfxParamPropStringMode property.

  • kOfxParamStringIsDirectoryPath

    Used to set a string parameter to be a directory path, value to be passed to a kOfxParamPropStringMode property.

  • kOfxParamStringIsLabel

    Use to set a string parameter to be a simple label, value to be passed to a kOfxParamPropStringMode property

  • kOfxParamStringIsRichTextFormat

    String value on the kOfxParamPropStringMode property of a string parameter (added in 1.3)

Group Parameters

This is typed by kOfxParamTypeGroup.

Group parameters allow all parameters to be arranged in a tree hierarchy. They have no value, they are purely a grouping element.

All parameters have a kOfxParamPropParent property, which is a string property naming the group parameter which is its parent.

The empty string “” is used to label the root of the parameter hierarchy, which is the default parent for all parameters.

Parameters inside a group are ordered by their order of addition to that group, which implies parameters in the root group are added in order of definition.

Any host based hierarchical GUI should use this hierarchy to order parameters (eg: animation sheets).

Page Parameters

This is typed by kOfxParamTypePage.

Page parameters are covered in detail in their own section.

Custom Parameters

This is typed by kOfxParamTypeCustom.

Custom parameters contain null terminated char * C strings, and may animate. They are designed to provide plugins with a way of storing data that is too complicated or impossible to store in a set of ordinary parameters.

If a custom parameter animates, it must set its kOfxParamPropCustomInterpCallbackV1 property, which points to a function with the following signature:

OfxStatus() OfxCustomParamInterpFuncV1 (OfxParamSetHandle instance, OfxPropertySetHandle inArgs, OfxPropertySetHandle outArgs)

Function prototype for custom parameter interpolation callback functions.

  • instance the plugin instance that this parameter occurs in

  • inArgs handle holding the following properties…

    • kOfxPropName - the name of the custom parameter to interpolate

    • kOfxPropTime - absolute time the interpolation is ocurring at

    • kOfxParamPropCustomValue - string property that gives the value of the two keyframes to interpolate, in this case 2D

    • kOfxParamPropInterpolationTime - 2D double property that gives the time of the two keyframes we are interpolating

    • kOfxParamPropInterpolationAmount - 1D double property indicating how much to interpolate between the two keyframes

  • outArgs handle holding the following properties to be set

    • kOfxParamPropCustomValue - the value of the interpolated custom parameter, in this case 1D

This function allows custom parameters to animate by performing interpolation between keys.

The plugin needs to parse the two strings encoding keyframes on either side of the time we need a value for. It should then interpolate a new value for it, encode it into a string and set the kOfxParamPropCustomValue property with this on the outArgs handle.

The interp value is a linear interpolation amount, however his may be derived from a cubic (or other) curve.

This function is used to interpolate keyframes in custom params.

Custom parameters have no interface by default. However,

  • if they animate, the host’s animation sheet/editor should present a keyframe/curve representation to allow positioning of keys and control of interpolation. The ‘normal’ (ie: paged or hierarchical) interface should not show any gui.

  • if the custom param sets its kOfxParamPropInteractV1 property, this should be used by the host in any normal (ie: paged or hierarchical) interface for the parameter.

Custom parameters are mandatory, as they are simply ASCII C strings. However, animation of custom parameters an support for an in editor interact is optional.

Push Button Parameters

This is typed by kOfxParamTypePushButton.

Push button parameters have no value, they are there so a plugin can detect if they have been pressed and perform some action. If pressed, a kOfxActionInstanceChanged action will be issued on the parameter with a kOfxPropChangeReason of kOfxChangeUserEdited.

Animation

By default the following parameter types animate…

The following types cannot animate…

The following may animate, depending on the host. Properties exist on the host to check this. If the host does support animation on them, then they do not animate by default. They are…

By default the OfxParameterSuiteV1::paramGetValue() will get the ‘current’ value of the parameter. To access values in a potentially animating parameter, use the OfxParameterSuiteV1::paramGetValueAtTime() function.

Keys can be manipulated in a parameter using a variety of functions, these are…

Parameter Interfaces

Parameters will be presented to the user in some form of interface. Typically on most host systems, this comes in three varieties…

  • a paged layout, with parameters spread over multiple controls pages (eg: the FLAME control pages)

  • a hierarchical layout, with parameters presented in a grouped tree (eg: the After Effects ‘effects’ window)

  • an animation sheet, showing animation curves and key frames. Typically this is hierarchical.

Most systems have an animation sheet and present one of either the paged or the hierarchical layouts.

Because a hierarchy of controls is explicitly set during plugin definition, the case of the animation sheet and hierarchial GUIs are taken care of explicitly.

Paged Parameter Editors

A paged layout of controls is difficult to standardise, as the size of the page and controls, how the controls are positioned on the page, how many controls appear on a page etc… depend very much upon the host implementation. A paged layout is ideally best described in the .XML resource supplied by the plugin, however a fallback page layout can be specified in OFX via the kOfxParamTypePage parameter type.

Several host properties are associated with paged layouts, these are…

Each page parameter represents a page of controls. The controls in that page are set by the plugin using the kOfxParamPropPageChild multi-dimensional string. For example…

OfxParamHandle  page;
gHost->paramDefine(plugin, kOfxParamTypePage, "Main", &page);

propHost->propSetString(page, kOfxParamPropPageChild, 0, "size");      // add the size parameter to the top left of the page
propHost->propSetString(page, kOfxParamPropPageChild, 1, kOfxParamPageSkipRow); // skip a row
propHost->propSetString(page, kOfxParamPropPageChild, 2, "centre");    // add the centre parameter
propHost->propSetString(page, kOfxParamPropPageChild, 3, kOfxParamPageSkipColumn); // skip a column, we are now at the top of the next column
propHost->propSetString(page, kOfxParamPropPageChild, 4, "colour"); // add the colour parameter

The host then places the parameters on that page in the order they were added, starting at the top left and going down columns, then across rows as they fill.

Note that there are two pseudo parameters names used to help control layout:

kOfxParamPageSkipRow

Pseudo parameter name used to skip a row in a page layout.

Passed as a value to the kOfxParamPropPageChild property.

See ParametersInterfacesPagedLayouts for more details.

kOfxParamPageSkipColumn

Pseudo parameter name used to skip a row in a page layout.

Passed as a value to the kOfxParamPropPageChild property.

See ParametersInterfacesPagedLayouts for more details.

These will help control how parameters are added to a page, allowing vertical or horizontal slots to be skipped.

A host sets the order of pages by using the instance’s kOfxPluginPropParamPageOrder property. Note that this property can vary from context to context, so you can exclude pages in contexts they are not useful in. For example…

OfxStatus describeInContext(OfxImageEffectHandle plugin)
{
...
    // order our pages of controls
    propHost->propSetString(paramSetProp, kOfxPluginPropParamPageOrder, 0, "Main");
    propHost->propSetString(paramSetProp, kOfxPluginPropParamPageOrder, 1, "Sampling");
    propHost->propSetString(paramSetProp, kOfxPluginPropParamPageOrder, 2, "Colour Correction");
    if(isGeneralContext)
       propHost->propSetString(paramSetProp, kOfxPluginPropParamPageOrder, 3, "Dance! Dance! Dance!");
...
}

Note

Parameters can be placed on more than a single page (this is often useful). Group parameters cannot be added to a page. Page parameters cannot be added to a page or group.

Instance changed callback

Whenever a parameter’s value changes, the host is expected to issue a call to the kOfxActionInstanceChanged action with the name of the parameter that changed and a reason indicating who triggered the change:

kOfxChangeUserEdited

String used as a value to kOfxPropChangeReason to indicate a user has changed something.

kOfxChangePluginEdited

String used as a value to kOfxPropChangeReason to indicate the plug-in itself has changed something.

kOfxChangeTime

String used as a value to kOfxPropChangeReason to a time varying object has changed due to a time change.

Parameter Undo/Redo

Hosts usually retain an undo/redo stack, so users can undo changes they make to a parameter. Often undos and redos are grouped together into an undo/redo block, where multiple parameters are dealt with as a single undo/redo event. Plugins need to be able to deal with this cleanly.

Parameters can be excluded from being undone/redone if they set the kOfxParamPropCanUndo property to 0.

If the plugin changes parameters values by calling the get and set value functions, they will ordinarily be put on the undo stack, one event per parameter that is changed. If the plugin wants to group sets of parameter changes into a single undo block and label that block, it should use the OfxParameterSuiteV1::paramEditBegin() and OfxParameterSuiteV1::paramEditEnd() functions.

An example would be a ‘preset’ choice parameter in a sky simulation whose job is to set other parameters to values that achieve certain looks, eg “Dusk”, “Midday”, “Stormy”, “Night” etc… This parameter has a value change callback which looks for kOfxChangeUserEdited then sets other parameters, sky colour, cloud density, sun position etc…. It also resets itself to the first choice, which says “Example Skys…”.

Rather than have many undo events appear on the undo stack for each individual parameter change, the effect groups them via the paramEditBegin/paramEditEnd and gets a single undo event. The ‘preset’ parameter would also not want to be undoable as it such an event is redundant. Note that as the ‘preset’ has been changed it will be sent another instance changed action, however it will have a reason of kOfxChangePluginEdited, which it ignores and so stops an infinite loop occurring.

XML Resource Specification for Parameters

Parameters can have various properties overridden via a separate XML based resource file.

Parameter Persistence

All parameters flagged with the kOfxParamPropPersistant property will persist when an effect is saved. How the effect is saved is completely up to the host, it may be in a file, a data base, where ever. We call a saved set of parameters a setup. A host will need to save the major version number of the plugin, as well as the plugin’s unique identifier, in any setup.

When an host loads a set up it should do so in the following manner…

  1. examines the setup for the major version number.

  2. find a matching plugin with that major version number, if multiple minor versions exist, the plugin with the largest minor version should be used.

  3. creates an instance of that plugin with its set of parameters.

  4. sets all those parameters to the defaults specified by the plugin.

  5. examines the setup for any persistent parameters, then sets the instance’s parameters to any found in it.

  6. calls create instance on the plugin.

It is not an error for a parameter to exist in the plugin but not the setup, and vice versa. This allows a plugin developer to modify parameter sets between point releases, generally by adding new params. The developer should be sure that the default values of any new parameters yield the same behaviour as before they were added, otherwise it would be a breach of the ‘major version means compatibility’ rule.

Parameter Properties Whose Type Vary

Some properties type depends on the kind of the parameter, eg: kOfxParamPropDefault is an int for a integer parameter but a double X 2 for a kOfxParamTypeDouble2D parameter.

The variant property types are as follows….

Types of Double Parameters

Double parameters can be used to represent a variety of data, by flagging what a double parameter is representing, a plug-in allows a host to represent to the user a more appropriate interface than a raw numerical value. Double parameters have the kOfxParamPropDoubleType property, which gives some meaning to the value. This can be one of…

Plain Double Parameters

Double parameters with their kOfxParamPropDoubleType property set to kOfxParamDoubleTypePlain are uninterpreted. The values represented to the user are what is reported back to the effect when values are retrieved. 1, 2 and 3D parameters can be flagged as kOfxParamDoubleTypePlain, which is the default.

For example a physical simulation plugin might have a ‘mass’ double parameter, which is in kilograms, which should be displayed and used as a raw value.

Angle Double Parameters

Double parameters with their kOfxParamPropDoubleType property set to kOfxParamDoubleTypeAngle are interpreted as angles. The host could use some fancy angle widget in it’s interface, representing degrees, angles mils whatever. However, the values returned to a plugin are always in degrees. Applicable to 1, 2 and 3D parameters.

For example a plugin that rotates an image in 3D would declare a 3D double parameter and flag that as an angle parameter and use the values as Euler angles for the rotation.

Scale Double Parameters

Double parameters with their kOfxParamPropDoubleType property set to kOfxParamDoubleTypeScale are interpreted as scale factors. The host can represent these as 1..100 percentages, 0..1 scale factors, fractions or whatever is appropriate for its interface. However, the plugin sees these as a straight scale factor, in the 0..1 range. Applicable to 1, 2 and 3D parameters.

For example a plugin that scales the size of an image would declare a ‘image scale’ parameter and use the raw value of that to scale the image.

Time Double Parameters

Double parameters with their kOfxParamPropDoubleType property set to kOfxParamDoubleTypeTime are interpreted as a time. The host can represent these as frames, seconds, milliseconds, millennia or whatever it feels is appropriate. However, a visual effect plugin sees such values in ‘frames’. Applicable only to 1D double parameters. It is an error to set this on any other type of double parameter.

For example a plugin that does motion blur would have a ‘shutter time’ parameter and flags that as a time parameter. The value returned would be used as the length of the shutter, in frames.

Absolute Time Double Parameters

Double parameters with their kOfxParamPropDoubleType property set to kOfxParamDoubleTypeAbsoluteTime are interpreted as an absolute time from the beginning of the effect. The host can represent these as frames, seconds, milliseconds, millennia or whatever it feels is appropriate. However, a plugin sees such values in ‘frames’ from the beginning of a clip. Applicable only to 1D double parameters. It is an error to set this on any other type of double parameter.

For example a plugin that stabalises all the images in a clip to a specific frame would have a reference frame parameter and declare that as an absolute time parameter and use its value to fetch a frame to stablise against.

Spatial Parameters

Parameters that can represent a size or position are essential. To that end there are several values of the kOfxParamPropDoubleType that say it should be interpreted as a size or position, in either one or two dimensions.

The original OFX API only specified normalised parameters, this proved to be somewhat more of a problem than expected. With the 1.2 version of the API, spatial parameters were introduced. Ideally these should be used and the normalised parameter types should be deprecated.

Plugins can check kOfxPropAPIVersion to see if these new parameter types are supported, in hosts with version 1.2 or greater they will be.

See the section on coordinate systems to understand some of the terms being discussed.

These parameter types represent a size or position in one or two dimensions in Canonical Coordinate. The host and plug-in get and set values in this coordinate system. Scaling to Pixel Coordinate is the responsibility of the effect.

The default value of a spatial parameter can be set in either a normalised coordinate system or the canonical coordinate system. This is controlled by the kOfxParamPropDefaultCoordinateSystem on the parameter descriptor with one of the following value:

kOfxParamCoordinatesCanonical

Define the canonical coordinate system.

kOfxParamCoordinatesNormalised

Define the normalised coordinate system.

Parameters can choose to be spatial in several ways…

Ideally, normalised parameters should be deprecated and no longer used if spatial parameters are available.

There are several values of the kOfxParamPropDoubleType that say it should be interpreted as a size or position. These are expressed and proportional to the current project’s size. This will allow the parameter to scale cleanly with project size changes and to be represented to the user in an appropriate range.

For example, the sensible X range of a visual effect plugin is the project’s width, say 768 pixels for a PAL D1 definition video project. The user sees the parameter as 0..768, the effect sees it as 0..1. So if the plug-in wanted to set the default value of an effect to be the centre of the image, it would flag a 2D parameter as normalised and set the defaults to be 0.5. The user would see this in the centre of the image, no matter the resolution of the project in question. The plugin would retrieve the parameter as 0..1 and scale it up to the project size to size to use.

Parameters can choose to be normalised in several ways…

See the section on coordinate systems on how to scale between normalised, canonical and pixel coordinates.

Double Parameters Defaults, Increments, Mins and Maxs

In all cases double parameters’ defaults, minimums and maximums are specified in the same space as the parameter, as is the increment in all cases but normalised parameters.

Normalised parameters specify their increments in canonical coordinates, rather than in normalised coordinates. So an increment of ‘1’ means 1 pixel, not ‘1 project width’, otherwise sliders would be a bit wild.

Parametric Parameters

Introduction

Parametric params are new for 1.2 and are optionally supported by host applications. They are specified via the kOfxParamTypeParametric identifier passed into OfxParameterSuiteV1::paramDefine()

These parameters are somewhat more complex than normal parameters and require their own set of functions to manage and manipulate them. The new OfxParametricParameterSuiteV1 is there to do that.

All the defines and suite definitions for parameteric parameters are defined in the file ofxParametricParam.h

Parametric parameters are in effect functions a plug-in can ask a host to arbitrarily evaluate for some value x. A classic use case would be for constructing look-up tables, a plug-in would ask the host to evaluate one at multiple values from 0 to 1 and use that to fill an array.

A host would probably represent this to a user as a cubic curve in a standard curve editor interface, or possibly through scripting. The user would then use this to define the ‘shape’ of the parameter.

The evaluation of such params is not the same as animation, they are returning values based on some arbitrary argument orthogonal to time, so to evaluate such a param, you need to pass a parametric position and time.

Often, you would want such a parametric parameter to be multi-dimensional, for example, a colour look-up table might want three values, one for red, green and blue. Rather than declare three separate parametric parameters, so a parametric parameter can be multi-dimensional.

Due to the nature of the underlying data, you cannot call certain functions in the ordinary parameter suite when manipulating a parametric parameter. All functions in the standard parameter suite are valid when called on a parametric parameter, with the exception of the following….

Defining Parametric Parameters

Parametric parameters are defined using the standard parameter suite function OfxParameterSuiteV1::paramDefine(). The descriptor returned by this call have several non standard parameter properties available. These are

Animating Parametric Parameters

Animation is an optional host feature for parametric parameters. Hosts flag whether they support this feature by setting the host descriptor property kOfxParamHostPropSupportsParametricAnimation.

Getting and Setting Values on a Parametric Parameters

Seeing as we need to pass in the parametric position and dimension to evaluate, parametric parameters need a new evaluation mechanism. They do this with the OfxParametricParameterSuiteV1::parametricParamGetValue() function. This function returns the value of the parameter at the given time, for the given dimension, adt the given parametric position,.

Parametric parameters are effectively interfaces to some sort of host based curve library. To get/set/delete points in the curve that represents a parameter, the new suite has several functions available to manipulate control points of the underlying curve.

To set the default value of a parametric parameter to anything but the identity, you use the control point setting functions in the new suite to set up a curve on the descriptor returned by OfxParameterSuiteV1::paramDefine(). Any instances later created, will have that curve as a default.

Example

This simple example defines a colour lookup table, defines a default, and show how to evaluate the curve

// describe our parameter in
static OfxStatus
describeInContext( OfxImageEffectHandle  effect,  OfxPropertySetHandle inArgs)
{
  ....
  // define it
  OfxPropertySetHandle props;
  gParamHost->paramDefine(paramSet, kOfxParamTypeParametric, "lookupTable", & props);

  // set standard names and labeles
  gPropHost->propSetString(props, kOfxParamPropHint, 0, "Colour lookup table");
  gPropHost->propSetString(props, kOfxParamPropScriptName, 0, "lookupTable");
  gPropHost->propSetString(props, kOfxPropLabel, 0, "Lookup Table");

  // define it as three dimensional
  gPropHost->propSetInt(props, kOfxParamPropParametricDimension, 0, 3);

  // label our dimensions are r/g/b
  gPropHost->propSetString(props, kOfxParamPropDimensionLabel, 0, "red");
  gPropHost->propSetString(props, kOfxParamPropDimensionLabel, 1, "green");
  gPropHost->propSetString(props, kOfxParamPropDimensionLabel, 2, "blue");

  // set the UI colour for each dimension
  for(int component = 0; component < 3; ++component) {
     gPropHost->propSetDouble(props, kOfxParamPropParametricUIColour, component * 3 + 0, component % 3 == 0 ? 1 : 0);
     gPropHost->propSetDouble(props, kOfxParamPropParametricUIColour, component * 3 + 1, component % 3 == 1 ? 1 : 0);
     gPropHost->propSetDouble(props, kOfxParamPropParametricUIColour, component * 3 + 2, component % 3 == 2 ? 1 : 0);
  }

  // set the min/max parametric range to 0..1
  gPropHost->propSetDouble(props, kOfxParamPropParametricRange, 0, 0.0);
  gPropHost->propSetDouble(props, kOfxParamPropParametricRange, 1, 1.0);

  // set a default curve, this example sets an invert
  OfxParamHandle descriptor;
  gParamHost->paramGetHandle(paramSet, "lookupTable", &descriptor, NULL);
  for(int component = 0; component < 3; ++component) {
    // add a control point at 0, value is 1
    gParametricParamHost->parametricParamAddControlPoint(descriptor,
                                                          component, // curve to set
                                                          0.0,   // time, ignored in this case, as we are not adding a ket
                                                          0.0,   // parametric position, zero
                                                          1.0,   // value to be, 1
                                                          false);   // don't add a key
    // add a control point at 1, value is 0
    gParametricParamHost->parametricParamAddControlPoint(descriptor, component, 0.0, 1.0, 0.0, false);
  }

  ...
}

void render8Bits(double currentFrame, otherStuff...)
{
   ...

   // make three luts from our curves
   unsigned char lut[3][256];

  OfxParamHandle param;
  gParamHost->paramGetHandle(paramSet, "lookupTable", &param, NULL);
  for(int component = 0; component < 3; ++component) {
    for(int position = 0; position < 256; ++position) {
      // position to evaluate the param at
      float parametricPos = float(position)/255.0f;

      // evaluate the parametric param
      float value;
      gParametricParamHost->parametricParamGetValue(param, component, currentFrame, parametricPos, &value);
      value = value * 255;
      value = clamp(value, 0, 255);

      // set that in the lut
      lut[dimension][position] = (unsigned char)value;
    }
  }
  ...
}

Setting Parameters

Plugins are free to set parameters in limited set of circumstances, typically relating to user interaction. You can only set parameters in the following actions passed to the plug-in’s main entry function…

Plugins can also set parameter values during the following actions passed to any of its interacts main entry function: