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 uninterpretted. 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 interpretted 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 interpretted 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 interpretted as a time. The host can represent these as frames, seconds, milliseconds, millenia 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 interpretted as an absolute time from the begining of the effect. The host can represent these as frames, seconds, milliseconds, millenia 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 interpretted as a size or position, in either one or two dimensions.

The original OFX API only specifed 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.

Spatial Double Parameters

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

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

Spatial Normalised Double Parameters

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 interpretted 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, cannonical 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 thier increments in cannonical 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.