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.
-
kOfxParamTypeInteger
-
kOfxParamTypeInteger2D
String to identify a param as a Two dimensional integer point parameter.
-
kOfxParamTypeInteger2D
-
kOfxParamTypeInteger3D
String to identify a param as a Three dimensional integer parameter.
-
kOfxParamTypeInteger3D
-
kOfxParamTypeDouble
String to identify a param as a Single valued floating point parameter
-
kOfxParamTypeDouble
-
kOfxParamTypeDouble2D
String to identify a param as a Two dimensional floating point parameter.
-
kOfxParamTypeDouble2D
-
kOfxParamTypeDouble3D
String to identify a param as a Three dimensional floating point parameter.
-
kOfxParamTypeDouble3D
-
kOfxParamTypeRGB
String to identify a param as a Red, Green and Blue colour parameter.
-
kOfxParamTypeRGB
-
kOfxParamTypeRGBA
String to identify a param as a Red, Green, Blue and Alpha colour parameter.
-
kOfxParamTypeRGBA
-
kOfxParamTypeBoolean
String to identify a param as a Single valued boolean parameter.
-
kOfxParamTypeBoolean
-
kOfxParamTypeChoice
String to identify a param as a Single valued, ‘one-of-many’ parameter.
-
kOfxParamTypeChoice
-
kOfxParamTypeStrChoice
String to identify a param as a string-valued ‘one-of-many’ parameter.
- Since
Version 1.5
-
kOfxParamTypeStrChoice
-
kOfxParamTypeString
String to identify a param as a String (UTF8) parameter.
-
kOfxParamTypeString
-
kOfxParamTypeCustom
String to identify a param as a Plug-in defined parameter.
-
kOfxParamTypeCustom
-
kOfxParamTypePushButton
String to identify a param as a PushButton parameter.
-
kOfxParamTypePushButton
-
kOfxParamTypeGroup
String to identify a param as a Grouping parameter.
-
kOfxParamTypeGroup
-
kOfxParamTypePage
String to identify a param as a page parameter.
-
kOfxParamTypePage
-
kOfxParamTypeParametric
String to identify a param as a single valued integer.
-
kOfxParamTypeParametric
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.
-
kOfxParamStringIsSingleLine
-
kOfxParamStringIsMultiLine
Used to set a string parameter to be multiple line, value to be passed to a kOfxParamPropStringMode property.
-
kOfxParamStringIsMultiLine
-
kOfxParamStringIsFilePath
Used to set a string parameter to be a file path, value to be passed to a kOfxParamPropStringMode property.
-
kOfxParamStringIsFilePath
-
kOfxParamStringIsDirectoryPath
Used to set a string parameter to be a directory path, value to be passed to a kOfxParamPropStringMode property.
-
kOfxParamStringIsDirectoryPath
-
kOfxParamStringIsLabel
Use to set a string parameter to be a simple label, value to be passed to a kOfxParamPropStringMode property
-
kOfxParamStringIsLabel
-
kOfxParamStringIsRichTextFormat
String value on the kOfxParamPropStringMode property of a string parameter (added in 1.3)
-
kOfxParamStringIsRichTextFormat
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 ininArgs
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 setkOfxParamPropCustomValue - the value of the interpolated custom parameter, in this case 1D
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.
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…
kOfxParamHostPropMaxPages
The maximum number of pages you may use, 0 implies an unpaged layoutkOfxParamHostPropPageRowColumnCount
The number of rows and columns for parameters in the paged layout.
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…
examines the setup for the major version number.
find a matching plugin with that major version number, if multiple minor versions exist, the plugin with the largest minor version should be used.
creates an instance of that plugin with its set of parameters.
sets all those parameters to the defaults specified by the plugin.
examines the setup for any persistent parameters, then sets the instance’s parameters to any found in it.
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….
kOfxParamTypeInteger
int X 1
kOfxParamTypeDouble
double X 1
kOfxParamTypeBoolean
int X 1
kOfxParamTypeChoice
int X 1
kOfxParamTypeStrChoice
char * X 1
kOfxParamTypeRGBA
double X 4 (normalised to 0..1 range)
kOfxParamTypeRGB
double X 3 (normalised to 0..1 range)
kOfxParamTypeDouble2D
double X 2
kOfxParamTypeInteger2D
int X 2
kOfxParamTypeDouble3D
double X 3
kOfxParamTypeInteger3D
int X 3
kOfxParamTypeString
char * X 1
kOfxParamTypeCustom
char * X 1
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…
-
kOfxParamDoubleTypePlain
value for the kOfxParamPropDoubleType property, indicating the parameter has no special interpretation and should be interpretted as a raw numeric value.
-
kOfxParamDoubleTypePlain
-
kOfxParamDoubleTypeAngle
value for the kOfxParamDoubleTypeAngle property, indicating the parameter is to be interpreted as an angle. See kOfxParamPropDoubleType.
-
kOfxParamDoubleTypeAngle
-
kOfxParamDoubleTypeScale
value for the kOfxParamPropDoubleType property, indicating the parameter is to be interpreted as a scale factor. See kOfxParamPropDoubleType.
-
kOfxParamDoubleTypeScale
-
kOfxParamDoubleTypeTime
value for the kOfxParamDoubleTypeAngle property, indicating the parameter is to be interpreted as a time. See kOfxParamPropDoubleType.
-
kOfxParamDoubleTypeTime
-
kOfxParamDoubleTypeAbsoluteTime
value for the kOfxParamDoubleTypeAngle property, indicating the parameter is to be interpreted as an absolute time from the start of the effect. See kOfxParamPropDoubleType.
-
kOfxParamDoubleTypeAbsoluteTime
-
kOfxParamDoubleTypeX
value for the kOfxParamPropDoubleType property, indicating a size in canonical coords in the X dimension. See kOfxParamPropDoubleType.
-
kOfxParamDoubleTypeX
-
kOfxParamDoubleTypeXAbsolute
value for the kOfxParamPropDoubleType property, indicating an absolute position in canonical coords in the X dimension. See kOfxParamPropDoubleType.
-
kOfxParamDoubleTypeXAbsolute
-
kOfxParamDoubleTypeY
value for the kOfxParamPropDoubleType property, indicating a size in canonical coords in the Y dimension. See kOfxParamPropDoubleType.
-
kOfxParamDoubleTypeY
-
kOfxParamDoubleTypeYAbsolute
value for the kOfxParamPropDoubleType property, indicating an absolute position in canonical coords in the Y dimension. See kOfxParamPropDoubleType.
-
kOfxParamDoubleTypeYAbsolute
-
kOfxParamDoubleTypeXY
value for the kOfxParamPropDoubleType property, indicating a 2D size in canonical coords. See kOfxParamPropDoubleType.
-
kOfxParamDoubleTypeXY
-
kOfxParamDoubleTypeXYAbsolute
value for the kOfxParamPropDoubleType property, indicating a 2D position in canonical coords. See kOfxParamPropDoubleType.
-
kOfxParamDoubleTypeXYAbsolute
-
kOfxParamDoubleTypeNormalisedX
value for the kOfxParamPropDoubleType property, indicating a size normalised to the X dimension. See kOfxParamPropDoubleType. — ofxParam.h
- Deprecated:
V1.3: Deprecated in favour of ::OfxParamDoubleTypeX V1.4: Removed
-
kOfxParamDoubleTypeNormalisedX
-
kOfxParamDoubleTypeNormalisedXAbsolute
value for the kOfxParamPropDoubleType property, indicating an absolute position normalised to the X dimension. See kOfxParamPropDoubleType. — ofxParam.h
- Deprecated:
V1.3: Deprecated in favour of ::OfxParamDoubleTypeXAbsolute V1.4: Removed
-
kOfxParamDoubleTypeNormalisedXAbsolute
-
kOfxParamDoubleTypeNormalisedY
value for the kOfxParamPropDoubleType property, indicating a size normalised to the Y dimension. See kOfxParamPropDoubleType. — ofxParam.h
- Deprecated:
V1.3: Deprecated in favour of ::OfxParamDoubleTypeY V1.4: Removed
-
kOfxParamDoubleTypeNormalisedY
-
kOfxParamDoubleTypeNormalisedYAbsolute
value for the kOfxParamPropDoubleType property, indicating an absolute position normalised to the Y dimension. See kOfxParamPropDoubleType. — ofxParam.h
- Deprecated:
V1.3: Deprecated in favour of ::OfxParamDoubleTypeYAbsolute V1.4: Removed
-
kOfxParamDoubleTypeNormalisedYAbsolute
-
kOfxParamDoubleTypeNormalisedXY
value for the kOfxParamPropDoubleType property, indicating normalisation to the X and Y dimension for 2D params. See kOfxParamPropDoubleType. — ofxParam.h
- Deprecated:
V1.3: Deprecated in favour of ::OfxParamDoubleTypeXY V1.4: Removed
-
kOfxParamDoubleTypeNormalisedXY
-
kOfxParamDoubleTypeNormalisedXYAbsolute
value for the kOfxParamPropDoubleType property, indicating normalisation to the X and Y dimension for a 2D param that can be interpretted as an absolute spatial position. See kOfxParamPropDoubleType. — ofxParam.h
- Deprecated:
V1.3: Deprecated in favour of kOfxParamDoubleTypeXYAbsolute V1.4: Removed
-
kOfxParamDoubleTypeNormalisedXYAbsolute
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…
kOfxParamDoubleTypeX
size in the X dimension, in canonical coords (1D double only),
kOfxParamDoubleTypeXAbsolute
positing in the X axis, in canonical coords (1D double only)
kOfxParamDoubleTypeY
size in the Y dimension, in canonical coords (1D double only),
kOfxParamDoubleTypeYAbsolute
positing in the Y axis, in canonical coords (1D double only)
kOfxParamDoubleTypeXY
2D size, in canonical coords (2D double only),
kOfxParamDoubleTypeXYAbsolute
2D position, in canonical coords. (2D double only).
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…
kOfxParamDoubleTypeNormalisedX
normalised size wrt to the project’s X dimension (1D only),
kOfxParamDoubleTypeNormalisedXAbsolute
normalised absolute position on the X axis (1D only)
kOfxParamDoubleTypeNormalisedY
normalised size wrt to the project’s Y dimension(1D only),
kOfxParamDoubleTypeNormalisedYAbsolute
normalised absolute position on the Y axis (1D only)
kOfxParamDoubleTypeNormalisedXY
normalised to the project’s X and Y size (2D only),
kOfxParamDoubleTypeNormalisedXYAbsolute
normalised to the projects X and Y size, and is an absolute
position on the image plane.
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
kOfxParamPropParametricDimension
the dimension of the parametric parameter,
kOfxParamPropParametricUIColour
the colour of the curves of a parametric parameter in any user
interface
kOfxParamPropParametricInteractBackground
a pointer to an interact entry point, which will be used to draw a
background under any user interface,
kOfxParamPropParametricRange
the min and max value that the parameter will be evaluated over.
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", ¶m, 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: