Struct 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 interrogatenumberOfKeys
pointer to integer where the return value is placed
Returns the number of keyframes in the parameter.
- Return:
kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid
-
OfxStatus (*paramGetKeyTime)(OfxParamHandle paramHandle, unsigned int nthKey, OfxTime *time)
Returns the time of the nth key.
paramHandle
parameter handle to interrogatenthKey
which key to ask about (0 to paramGetNumKeys -1), ordered by timetime
pointer to OfxTime where the return value is placed
- Return:
kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid
kOfxStatErrBadIndex - the nthKey does not exist
-
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 searchtime
what time to search fromdirection
== 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:
kOfxStatOK - all was OK
kOfxStatFailed - if the search failed to find a key
kOfxStatErrBadHandle - if the parameter handle was invalid
-
OfxStatus (*paramDeleteKey)(OfxParamHandle paramHandle, OfxTime time)
Deletes a keyframe if one exists at the given time.
paramHandle
parameter handle to delete the key fromtime
time at which a keyframe is
- Return:
kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid
kOfxStatErrBadIndex - no key at the given time
-
OfxStatus (*paramDeleteAllKeys)(OfxParamHandle paramHandle)
Deletes all keyframes from a parameter.
paramHandle
parameter handle to delete the keys fromname
parameter to delete the keyframes frome is
- Return:
kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid
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 parameterparamType
type of the parameter to create, one of the kOfxParamType* #definesname
unique name of the parameterpropertySet
if not null, a pointer to the parameter descriptor’s property set will be placed here.
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:
kOfxStatOK - the parameter was created correctly
kOfxStatErrBadHandle - if the plugin handle was invalid
kOfxStatErrExists - if a parameter of that name exists already in this plugin
kOfxStatErrUnknown - if the type is unknown
kOfxStatErrUnsupported - if the type is known but unsupported
-
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 fromname
parameter to ask aboutparam
pointer to a param handle, the value is returned herepropertySet
if not null, a pointer to the parameter’s property set will be placed here.
- Return:
kOfxStatOK - the parameter was found and returned
kOfxStatErrBadHandle - if the plugin handle was invalid
kOfxStatErrUnknown - if the type is unknown
-
OfxStatus (*paramSetGetPropertySet)(OfxParamSetHandle paramSet, OfxPropertySetHandle *propHandle)
Retrieves the property set handle for the given parameter set.
paramSet
parameter set to get the property set forpropHandle
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:
kOfxStatOK - the property set was found and returned
kOfxStatErrBadHandle - if the paramter handle was invalid
kOfxStatErrUnknown - if the type is unknown
-
OfxStatus (*paramGetPropertySet)(OfxParamHandle param, OfxPropertySetHandle *propHandle)
Retrieves the property set handle for the given parameter.
param
parameter to get the property set forpropHandle
pointer to a the property set handle, value is returedn her
- Return:
kOfxStatOK - the property set was found and returned
kOfxStatErrBadHandle - if the paramter handle was invalid
kOfxStatErrUnknown - if the type is unknown
-
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
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:
kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid
-
OfxStatus (*paramGetValueAtTime)(OfxParamHandle paramHandle, OfxTime time, ...)
Gets the value of a parameter at a specific time.
paramHandle
parameter handle to fetch value fromtime
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
- Return:
kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid
-
OfxStatus (*paramGetDerivative)(OfxParamHandle paramHandle, OfxTime time, ...)
Gets the derivative of a parameter at a specific time.
paramHandle
parameter handle to fetch value fromtime
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
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:
kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid
-
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 fromtime1
where to start evaluating the integraltime2
where to stop evaluating the integral… one or more pointers to variables of the relevant type to hold the parameter’s integral
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:
kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid
-
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
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:
kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid
-
OfxStatus (*paramSetValueAtTime)(OfxParamHandle paramHandle, OfxTime time, ...)
Keyframes the value of a parameter at a specific time.
paramHandle
parameter handle to set value intime
at what point in time to set the keyframe… one or more variables of the relevant type to hold the parameter’s value
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:
kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid
-
OfxStatus (*paramCopy)(OfxParamHandle paramTo, OfxParamHandle paramFrom, OfxTime dstOffset, const OfxRangeD *frameRange)
Copies one parameter to another, including any animation etc…
paramTo
parameter to setparamFrom
parameter to copy fromdstOffset
temporal offset to apply to keys when writing to the paramToframeRange
if paramFrom has animation, and frameRange is not null, only this range of keys will be copied
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:
kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid
-
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 happeningname
label to attach to any undo/redo string UTF8
See also OfxParameterSuiteV1::paramEditEnd
Note
paramEditBegin
should only be called from within a kOfxActionInstanceChanged or interact action.- Return:
kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the instance handle was invalid
-
OfxStatus (*paramEditEnd)(OfxParamSetHandle paramSet)
Used to group any parameter changes for undo/redo purposes.
paramSet
parameter set in which this is happening
See also OfxParameterSuiteV1::paramEditBegin
Note
paramEditEnd
should only be called from within a kOfxActionInstanceChanged or interact action.- Return:
kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the instance handle was invalid
-
OfxStatus (*paramGetNumKeys)(OfxParamHandle paramHandle, unsigned int *numberOfKeys)