Parameter Types
Prev   Chapter 9. Effect Parameters   Next

Parameter Types

There are seventeen types of parameter. These are

  • integers, 1, 2 and 3 dimensional
  • doubles, 1, 2 and 3 dimensional
  • colour, RGB and RGB + Alpha
  • booleans
  • choice
  • string
  • custom
  • push button
  • group
  • page
  • parametric

Multidimensional Parameters

Some parameter types are multi dimensional, these are...

  • kOfxParamTypeDouble2D - 2 doubles
  • kOfxParamTypeInteger2D - int X 2
  • kOfxParamTypeDouble3D - double X 3
  • kOfxParamTypeInteger3D - int X 3
  • kOfxParamTypeRGB - double X 3
  • kOfxParamTypeRGBA - double X 4
  • kOfxParamTypeParametric - variable dimension

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.

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.

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 - single line string
  • kOfxParamStringIsMultiLine - multi line string
  • kOfxParamStringIsFilePath - single line string interpretted as a file path on the computer this should have appropriate file browser UIs available
  • kOfxParamStringIsDirectoryPath - similar to the above, but refers to a directory rather than a file
  • kOfxParamStringIsLabel - string behaves as a pseudo parameter and acts as a label on the interface in this case the string is not editable by the user

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 OfxCustomParamInterpFuncV1 function. 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 .

Prev   Up   Next
Defining Parameters  Home  Animation