OfxParametricParameterSuiteV1

struct OfxParametricParameterSuiteV1

The OFX suite used to define and manipulate ‘parametric’ parameters.

This is an optional suite.

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, it would be better to have one such parameter with multiple values in it.

The major complication with these parameters is how to allow a plug-in to set values, and defaults. The default default value of a parametric curve is to be an identity lookup. If a plugin wishes to set a different default value for a curve, it can use the suite to set key/value pairs on the descriptor of the param. When a new instance is made, it will have these curve values as a default.

Public Members

OfxStatus (*parametricParamGetValue)(OfxParamHandle param, int curveIndex, OfxTime time, double parametricPosition, double *returnValue)

Evaluates a parametric parameter.

  • param handle to the parametric parameter

  • curveIndex which dimension to evaluate

  • time the time to evaluate to the parametric param at

  • parametricPosition the position to evaluate the parametric param at

  • returnValue pointer to a double where a value is returned

Return:

OfxStatus (*parametricParamGetNControlPoints)(OfxParamHandle param, int curveIndex, double time, int *returnValue)

Returns the number of control points in the parametric param.

  • param handle to the parametric parameter

  • curveIndex which dimension to check

  • time the time to check

  • returnValue pointer to an integer where the value is returned.

Return:

OfxStatus (*parametricParamGetNthControlPoint)(OfxParamHandle param, int curveIndex, double time, int nthCtl, double *key, double *value)

Returns the key/value pair of the nth control point.

  • param handle to the parametric parameter

  • curveIndex which dimension to check

  • time the time to check

  • nthCtl the nth control point to get the value of

  • key pointer to a double where the key will be returned

  • value pointer to a double where the value will be returned

Return:

OfxStatus (*parametricParamSetNthControlPoint)(OfxParamHandle param, int curveIndex, double time, int nthCtl, double key, double value, bool addAnimationKey)

Modifies an existing control point on a curve.

  • param handle to the parametric parameter

  • curveIndex which dimension to set

  • time the time to set the value at

  • nthCtl the control point to modify

  • key key of the control point

  • value value of the control point

  • addAnimationKey if the param is an animatable, setting this to true will force an animation keyframe to be set as well as a curve key, otherwise if false, a key will only be added if the curve is already animating.

This modifies an existing control point. Note that by changing key, the order of the control point may be modified (as you may move it before or after anther point). So be careful when iterating over a curves control points and you change a key.

Return:

OfxStatus (*parametricParamAddControlPoint)(OfxParamHandle param, int curveIndex, double time, double key, double value, bool addAnimationKey)

Adds a control point to the curve.

  • param handle to the parametric parameter

  • curveIndex which dimension to set

  • time the time to set the value at

  • key key of the control point

  • value value of the control point

  • addAnimationKey if the param is an animatable, setting this to true will force an animation keyframe to be set as well as a curve key, otherwise if false, a key will only be added if the curve is already animating.

This will add a new control point to the given dimension of a parametric parameter. If a key exists sufficiently close to ‘key’, then it will be set to the indicated control point.

Return:

OfxStatus (*parametricParamDeleteControlPoint)(OfxParamHandle param, int curveIndex, int nthCtl)

Deletes the nth control point from a parametric param.

  • param handle to the parametric parameter

  • curveIndex which dimension to delete

  • nthCtl the control point to delete

OfxStatus (*parametricParamDeleteAllControlPoints)(OfxParamHandle param, int curveIndex)

Delete all curve control points on the given param.

  • param handle to the parametric parameter

  • curveIndex which dimension to clear