OfxParameterSuiteV1

struct OfxParameterSuiteV1

The OFX suite used to define and manipulate user visible parameters.

Keyframe Handling

These functions allow the plug-in to delete and get information about keyframes.

To set keyframes, use paramSetValueAtTime().

paramGetKeyTime and paramGetKeyIndex use indices to refer to keyframes. Keyframes are stored by the host in increasing time order, so time(kf[i]) < time(kf[i+1]). Keyframe indices will change whenever keyframes are added, deleted, or moved in time, whether by the host or by the plug-in. They may vary between actions if the user changes a keyframe. The keyframe indices will not change within a single action.

OfxStatus (*paramGetNumKeys)(OfxParamHandle paramHandle, unsigned int *numberOfKeys)

Returns the number of keyframes in the parameter.

  • paramHandle parameter handle to interrogate

  • numberOfKeys pointer to integer where the return value is placed

V1.3: This function can be called the kOfxActionInstanceChanged action and during image effect analysis render passes. V1.4: This function can be called the kOfxActionInstanceChanged action

Returns the number of keyframes in the parameter.

Return:

OfxStatus (*paramGetKeyTime)(OfxParamHandle paramHandle, unsigned int nthKey, OfxTime *time)

Returns the time of the nth key.

  • paramHandle parameter handle to interrogate

  • nthKey which key to ask about (0 to paramGetNumKeys -1), ordered by time

  • time pointer to OfxTime where the return value is placed

Return:

OfxStatus (*paramGetKeyIndex)(OfxParamHandle paramHandle, OfxTime time, int direction, int *index)

Finds the index of a keyframe at/before/after a specified time.

  • paramHandle parameter handle to search

  • time what time to search from

  • direction

    • == 0 indicates search for a key at the indicated time (some small delta)

    • > 0 indicates search for the next key after the indicated time

    • < 0 indicates search for the previous key before the indicated time

  • index pointer to an integer which in which the index is returned set to -1 if no key was found

Return:

OfxStatus (*paramDeleteKey)(OfxParamHandle paramHandle, OfxTime time)

Deletes a keyframe if one exists at the given time.

  • paramHandle parameter handle to delete the key from

  • time time at which a keyframe is

Return:

OfxStatus (*paramDeleteAllKeys)(OfxParamHandle paramHandle)

Deletes all keyframes from a parameter.

  • paramHandle parameter handle to delete the keys from

  • name parameter to delete the keyframes frome is

V1.3: This function can be called the kOfxActionInstanceChanged action and during image effect analysis render passes. V1.4: This function can be called the kOfxActionInstanceChanged action

Return:

Public Members

OfxStatus (*paramDefine)(OfxParamSetHandle paramSet, const char *paramType, const char *name, OfxPropertySetHandle *propertySet)

Defines a new parameter of the given type in a describe action.

  • paramSet handle to the parameter set descriptor that will hold this parameter

  • paramType type of the parameter to create, one of the kOfxParamType* #defines

  • name unique name of the parameter

  • propertySet if not null, a pointer to the parameter descriptor’s property set will be placed here.

This function defines a parameter in a parameter set and returns a property set which is used to describe that parameter.

This function does not actually create a parameter, it only says that one should exist in any subsequent instances. To fetch an parameter instance paramGetHandle must be called on an instance.

This function can always be called in one of a plug-in’s “describe” functions which defines the parameter sets common to all instances of a plugin.

Return:

OfxStatus (*paramGetHandle)(OfxParamSetHandle paramSet, const char *name, OfxParamHandle *param, OfxPropertySetHandle *propertySet)

Retrieves the handle for a parameter in a given parameter set.

  • paramSet instance of the plug-in to fetch the property handle from

  • name parameter to ask about

  • param pointer to a param handle, the value is returned here

  • propertySet if not null, a pointer to the parameter’s property set will be placed here.

Parameter handles retrieved from an instance are always distinct in each instance. The paramter handle is valid for the life-time of the instance. Parameter handles in instances are distinct from paramter handles in plugins. You cannot call this in a plugin’s describe function, as it needs an instance to work on.

Return:

OfxStatus (*paramSetGetPropertySet)(OfxParamSetHandle paramSet, OfxPropertySetHandle *propHandle)

Retrieves the property set handle for the given parameter set.

  • paramSet parameter set to get the property set for

  • propHandle pointer to a the property set handle, value is returedn her

Note

The property handle belonging to a parameter set is the same as the property handle belonging to the plugin instance.

Return:

OfxStatus (*paramGetPropertySet)(OfxParamHandle param, OfxPropertySetHandle *propHandle)

Retrieves the property set handle for the given parameter.

  • param parameter to get the property set for

  • propHandle pointer to a the property set handle, value is returedn her

The property handle is valid for the lifetime of the parameter, which is the lifetime of the instance that owns the parameter

Return:

OfxStatus (*paramGetValue)(OfxParamHandle paramHandle, ...)

Gets the current value of a parameter,.

  • paramHandle parameter handle to fetch value from

  • … one or more pointers to variables of the relevant type to hold the parameter’s value

This gets the current value of a parameter. The varargs … argument needs to be pointer to C variables of the relevant type for this parameter. Note that params with multiple values (eg Colour) take multiple args here. For example…

  OfxParamHandle myDoubleParam, *myColourParam;
  ofxHost->paramGetHandle(instance, "myDoubleParam", &myDoubleParam);
  double myDoubleValue;
  ofxHost->paramGetValue(myDoubleParam, &myDoubleValue);
  ofxHost->paramGetHandle(instance, "myColourParam", &myColourParam);
  double myR, myG, myB;
  ofxHost->paramGetValue(myColourParam, &myR, &myG, &myB);

Note

paramGetValue should only be called from within a kOfxActionInstanceChanged or interact action and never from the render actions (which should always use paramGetValueAtTime).

Return:

OfxStatus (*paramGetValueAtTime)(OfxParamHandle paramHandle, OfxTime time, ...)

Gets the value of a parameter at a specific time.

  • paramHandle parameter handle to fetch value from

  • time at what point in time to look up the parameter

  • … one or more pointers to variables of the relevant type to hold the parameter’s value

This gets the current value of a parameter. The varargs needs to be pointer to C variables of the relevant type for this parameter. See OfxParameterSuiteV1::paramGetValue for notes on the varags list

Return:

OfxStatus (*paramGetDerivative)(OfxParamHandle paramHandle, OfxTime time, ...)

Gets the derivative of a parameter at a specific time.

  • paramHandle parameter handle to fetch value from

  • time at what point in time to look up the parameter

  • … one or more pointers to variables of the relevant type to hold the parameter’s derivative

This gets the derivative of the parameter at the indicated time.

The varargs needs to be pointer to C variables of the relevant type for this parameter. See OfxParameterSuiteV1::paramGetValue for notes on the varags list.

Only double and colour params can have their derivatives found.

Return:

OfxStatus (*paramGetIntegral)(OfxParamHandle paramHandle, OfxTime time1, OfxTime time2, ...)

Gets the integral of a parameter over a specific time range,.

  • paramHandle parameter handle to fetch integral from

  • time1 where to start evaluating the integral

  • time2 where to stop evaluating the integral

  • … one or more pointers to variables of the relevant type to hold the parameter’s integral

This gets the integral of the parameter over the specified time range.

The varargs needs to be pointer to C variables of the relevant type for this parameter. See OfxParameterSuiteV1::paramGetValue for notes on the varags list.

Only double and colour params can be integrated.

Return:

OfxStatus (*paramSetValue)(OfxParamHandle paramHandle, ...)

Sets the current value of a parameter.

  • paramHandle parameter handle to set value in

  • … one or more variables of the relevant type to hold the parameter’s value

This sets the current value of a parameter. The varargs … argument needs to be values of the relevant type for this parameter. Note that params with multiple values (eg Colour) take multiple args here. For example… 
  ofxHost->paramSetValue(instance, "myDoubleParam", double(10));
  ofxHost->paramSetValue(instance, "myColourParam", double(pix.r), double(pix.g), double(pix.b));

Note

paramSetValue should only be called from within a kOfxActionInstanceChanged or interact action.

Return:

OfxStatus (*paramSetValueAtTime)(OfxParamHandle paramHandle, OfxTime time, ...)

Keyframes the value of a parameter at a specific time.

  • paramHandle parameter handle to set value in

  • time at what point in time to set the keyframe

  • … one or more variables of the relevant type to hold the parameter’s value

This sets a keyframe in the parameter at the indicated time to have the indicated value. The varargs … argument needs to be values of the relevant type for this parameter. See the note on OfxParameterSuiteV1::paramSetValue for more detail

V1.3: This function can be called the kOfxActionInstanceChanged action and during image effect analysis render passes. V1.4: This function can be called the kOfxActionInstanceChanged action

Note

paramSetValueAtTime should only be called from within a kOfxActionInstanceChanged or interact action.

Return:

OfxStatus (*paramCopy)(OfxParamHandle paramTo, OfxParamHandle paramFrom, OfxTime dstOffset, const OfxRangeD *frameRange)

Copies one parameter to another, including any animation etc…

  • paramTo parameter to set

  • paramFrom parameter to copy from

  • dstOffset temporal offset to apply to keys when writing to the paramTo

  • frameRange if paramFrom has animation, and frameRange is not null, only this range of keys will be copied

This copies the value of paramFrom to paramTo, including any animation it may have. All the previous values in paramTo will be lost.

To choose all animation in paramFrom set frameRange to [0, 0]

V1.3: This function can be called the kOfxActionInstanceChanged action and during image effect analysis render passes. V1.4: This function can be called the kOfxActionInstanceChanged action

Pre:

  • Both parameters must be of the same type.

Return:

OfxStatus (*paramEditBegin)(OfxParamSetHandle paramSet, const char *name)

Used to group any parameter changes for undo/redo purposes.

  • paramSet the parameter set in which this is happening

  • name label to attach to any undo/redo string UTF8

If a plugin calls paramSetValue/paramSetValueAtTime on one or more parameters, either from custom GUI interaction or some analysis of imagery etc.. this is used to indicate the start of a set of a parameter changes that should be considered part of a single undo/redo block.

See also OfxParameterSuiteV1::paramEditEnd

Note

paramEditBegin should only be called from within a kOfxActionInstanceChanged or interact action.

Return:

OfxStatus (*paramEditEnd)(OfxParamSetHandle paramSet)

Used to group any parameter changes for undo/redo purposes.

  • paramSet parameter set in which this is happening

If a plugin calls paramSetValue/paramSetValueAtTime on one or more parameters, either from custom GUI interaction or some analysis of imagery etc.. this is used to indicate the end of a set of parameter changes that should be considerred part of a single undo/redo block

See also OfxParameterSuiteV1::paramEditBegin

Note

paramEditEnd should only be called from within a kOfxActionInstanceChanged or interact action.

Return: