File ofxParam.h
This header contains the suite definition to manipulate host side parameters.
For more details go see ParametersPage
Defines
-
kOfxParameterSuite
string value to the kOfxPropType property for all parameters
-
kOfxTypeParameter
string value on the kOfxPropType property for all parameter definitions (ie: the handle returned in describe)
-
kOfxTypeParameterInstance
string value on the kOfxPropType property for all parameter instances
-
kOfxParamTypeInteger
String to identify a param as a single valued integer.
-
kOfxParamTypeDouble
String to identify a param as a Single valued floating point parameter
-
kOfxParamTypeBoolean
String to identify a param as a Single valued boolean parameter.
-
kOfxParamTypeChoice
String to identify a param as a Single valued, ‘one-of-many’ parameter.
-
kOfxParamTypeStrChoice
String to identify a param as a string-valued ‘one-of-many’ parameter.
- Since
Version 1.5
-
kOfxParamTypeRGBA
String to identify a param as a Red, Green, Blue and Alpha colour parameter.
-
kOfxParamTypeRGB
String to identify a param as a Red, Green and Blue colour parameter.
-
kOfxParamTypeDouble2D
String to identify a param as a Two dimensional floating point parameter.
-
kOfxParamTypeInteger2D
String to identify a param as a Two dimensional integer point parameter.
-
kOfxParamTypeDouble3D
String to identify a param as a Three dimensional floating point parameter.
-
kOfxParamTypeInteger3D
String to identify a param as a Three dimensional integer parameter.
-
kOfxParamTypeString
String to identify a param as a String (UTF8) parameter.
-
kOfxParamTypeCustom
String to identify a param as a Plug-in defined parameter.
-
kOfxParamTypeGroup
String to identify a param as a Grouping parameter.
-
kOfxParamTypePage
String to identify a param as a page parameter.
-
kOfxParamTypePushButton
String to identify a param as a PushButton parameter.
-
kOfxParamHostPropSupportsCustomAnimation
Indicates if the host supports animation of custom parameters.
Type - int X 1
Property Set - host descriptor (read only)
Value Values - 0 or 1
-
kOfxParamHostPropSupportsStringAnimation
Indicates if the host supports animation of string params.
Type - int X 1
Property Set - host descriptor (read only)
Valid Values - 0 or 1
-
kOfxParamHostPropSupportsBooleanAnimation
Indicates if the host supports animation of boolean params.
Type - int X 1
Property Set - host descriptor (read only)
Valid Values - 0 or 1
-
kOfxParamHostPropSupportsChoiceAnimation
Indicates if the host supports animation of choice params.
Type - int X 1
Property Set - host descriptor (read only)
Valid Values - 0 or 1
-
kOfxParamHostPropSupportsCustomInteract
Indicates if the host supports custom interacts for parameters.
Type - int X 1
Property Set - host descriptor (read only)
Valid Values - 0 or 1
Currently custom interacts for parameters can only be drawn using OpenGL. APIs will be added later to support using the new Draw Suite.
-
kOfxParamHostPropMaxParameters
Indicates the maximum numbers of parameters available on the host.
Type - int X 1
Property Set - host descriptor (read only)
If set to -1 it implies unlimited number of parameters.
-
kOfxParamHostPropMaxPages
Indicates the maximum number of parameter pages.
Type - int X 1
Property Set - host descriptor (read only)
If there is no limit to the number of pages on a host, set this to -1.
Hosts that do not support paged parameter layout should set this to zero.
-
kOfxParamHostPropPageRowColumnCount
This indicates the number of parameter rows and coloumns on a page.
Type - int X 2
Property Set - host descriptor (read only)
If the host has supports paged parameter layout, used dimension 0 as the number of columns per page and dimension 1 as the number of rows per page.
-
kOfxParamPageSkipRow
Pseudo parameter name used to skip a row in a page layout.
Passed as a value to the kOfxParamPropPageChild property.
See ParametersInterfacesPagedLayouts for more details.
-
kOfxParamPageSkipColumn
Pseudo parameter name used to skip a row in a page layout.
Passed as a value to the kOfxParamPropPageChild property.
See ParametersInterfacesPagedLayouts for more details.
-
kOfxParamPropInteractV1
Overrides the parameter’s standard user interface with the given interact.
Type - pointer X 1
Property Set - plugin parameter descriptor (read/write) and instance (read only)
Default - NULL
Valid Values - must point to a OfxPluginEntryPoint
If set, the parameter’s normal interface is replaced completely by the interact gui.
Currently custom interacts for parameters can only be drawn using OpenGL. APIs will be added later to support using the new Draw Suite.
-
kOfxParamPropInteractSize
The size of a parameter instance’s custom interface in screen pixels.
Type - double x 2
Property Set - plugin parameter instance (read only)
This is set by a host to indicate the current size of a custom interface if the plug-in has one. If not this is set to (0,0).
-
kOfxParamPropInteractSizeAspect
The preferred aspect ratio of a parameter’s custom interface.
Type - double x 1
Property Set - plugin parameter descriptor (read/write) and instance (read only)
Default - 1.0
Valid Values - greater than or equal to 0.0
If set to anything other than 0.0, the custom interface for this parameter will be of a size with this aspect ratio (x size/y size).
-
kOfxParamPropInteractMinimumSize
The minimum size of a parameter’s custom interface, in screen pixels.
Type - double x 2
Property Set - plugin parameter descriptor (read/write) and instance (read only)
Default - 10,10
Valid Values - greater than (0, 0)
Any custom interface will not be less than this size.
-
kOfxParamPropInteractPreferedSize
The preferred size of a parameter’s custom interface.
Type - int x 2
Property Set - plugin parameter descriptor (read/write) and instance (read only)
Default - 10,10
Valid Values - greater than (0, 0)
A host should attempt to set a parameter’s custom interface on a parameter to be this size if possible, otherwise it will be of kOfxParamPropInteractSizeAspect aspect but larger than kOfxParamPropInteractMinimumSize.
-
kOfxParamPropType
The type of a parameter.
Type - C string X 1
Property Set - plugin parameter descriptor (read only) and instance (read only)
This string will be set to the type that the parameter was create with.
-
kOfxParamPropAnimates
Flags whether a parameter can animate.
Type - int x 1
Property Set - plugin parameter descriptor (read/write) and instance (read only)
Default - 1
Valid Values - 0 or 1
A plug-in uses this property to indicate if a parameter is able to animate.
-
kOfxParamPropCanUndo
Flags whether changes to a parameter should be put on the undo/redo stack.
Type - int x 1
Property Set - plugin parameter descriptor (read/write) and instance (read only)
Default - 1
Valid Values - 0 or 1
-
kOfxPropParamSetNeedsSyncing
States whether the plugin needs to resync its private data.
Type - int X 1
Property Set - param set instance (read/write)
Default - 0
Valid Values -
0 - no need to sync
1 - paramset is not synced
The plugin should set this flag to true whenever any internal state has not been flushed to the set of params.
The host will examine this property each time it does a copy or save operation on the instance. If it is set to 1, the host will call SyncPrivateData and then set it to zero before doing the copy/save. If it is set to 0, the host will assume that the param data correctly represents the private state, and will not call SyncPrivateData before copying/saving. If this property is not set, the host will always call SyncPrivateData before copying or saving the effect (as if the property were set to 1 — but the host will not create or modify the property).
-
kOfxParamPropIsAnimating
Flags whether a parameter is currently animating.
Type - int x 1
Property Set - plugin parameter instance (read only)
Valid Values - 0 or 1
Set by a host on a parameter instance to indicate if the parameter has a non-constant value set on it. This can be as a consequence of animation or of scripting modifying the value, or of a parameter being connected to an expression in the host.
-
kOfxParamPropPluginMayWrite
Flags whether the plugin will attempt to set the value of a parameter in some callback or analysis pass.
Type - int x 1
Property Set - plugin parameter descriptor (read/write) and instance (read only)
Default - 0
Valid Values - 0 or 1
This is used to tell the host whether the plug-in is going to attempt to set the value of the parameter.
- Deprecated:
v1.4: deprecated - to be removed in 1.5
-
kOfxParamPropPersistant
Flags whether the value of a parameter should persist.
Type - int x 1
Property Set - plugin parameter descriptor (read/write) and instance (read only)
Default - 1
Valid Values - 0 or 1
This is used to tell the host whether the value of the parameter is important and should be save in any description of the plug-in.
-
kOfxParamPropEvaluateOnChange
Flags whether changing a parameter’s value forces an evalution (ie: render),.
Type - int x 1
Property Set - plugin parameter descriptor (read/write) and instance (read/write only)
Default - 1
Valid Values - 0 or 1
This is used to indicate if the value of a parameter has any affect on an effect’s output, eg: the parameter may be purely for GUI purposes, and so changing its value should not trigger a re-render.
-
kOfxParamPropSecret
Flags whether a parameter should be exposed to a user,.
Type - int x 1
Property Set - plugin parameter descriptor (read/write) and instance (read/write)
Default - 0
Valid Values - 0 or 1
If secret, a parameter is not exposed to a user in any interface, but should otherwise behave as a normal parameter.
Secret params are typically used to hide important state detail that would otherwise be unintelligible to a user, for example the result of a statical analysis that might need many parameters to store.
-
kOfxParamPropScriptName
The value to be used as the id of the parameter in a host scripting language.
Type - ASCII C string X 1,
Property Set - plugin parameter descriptor (read/write) and instance (read only),
Default - the unique name the parameter was created with.
Valid Values - ASCII string unique to all parameters in the plug-in.
Many hosts have a scripting language that they use to set values of parameters and more. If so, this is the name of a parameter in such scripts.
-
kOfxParamPropCacheInvalidation
Specifies how modifying the value of a param will affect any output of an effect over time.
Type - C string X 1
Property Set - plugin parameter descriptor (read/write) and instance (read only),
Default - kOfxParamInvalidateValueChange
Valid Values - This must be one of
Imagine an effect with an animating parameter in a host that caches rendered output. Think of the what happens when you add a new key frame. -If the parameter represents something like an absolute position, the cache will only need to be invalidated for the range of frames that keyframe affects.
If the parameter represents something like a speed which is integrated, the cache will be invalidated from the keyframe until the end of the clip.
There are potentially other situations where the entire cache will need to be invalidated (though I can’t think of one off the top of my head).
-
kOfxParamInvalidateValueChange
Used as a value for the kOfxParamPropCacheInvalidation property.
-
kOfxParamInvalidateValueChangeToEnd
Used as a value for the kOfxParamPropCacheInvalidation property.
-
kOfxParamInvalidateAll
Used as a value for the kOfxParamPropCacheInvalidation property.
-
kOfxParamPropHint
A hint to the user as to how the parameter is to be used.
Type - UTF8 C string X 1
Property Set - plugin parameter descriptor (read/write) and instance (read/write),
Default - “”
-
kOfxParamPropDefault
The default value of a parameter.
Type - The type is dependant on the parameter type as is the dimension.
Property Set - plugin parameter descriptor (read/write) and instance (read/write only),
Default - 0 cast to the relevant type (or “” for strings and custom parameters)
The exact type and dimension is dependant on the type of the parameter. These are….
kOfxParamTypeInteger - integer property of one dimension
kOfxParamTypeDouble - double property of one dimension
kOfxParamTypeBoolean - integer property of one dimension
kOfxParamTypeChoice - integer property of one dimension
kOfxParamTypeStrChoice - string property of one dimension
kOfxParamTypeRGBA - double property of four dimensions
kOfxParamTypeRGB - double property of three dimensions
kOfxParamTypeDouble2D - double property of two dimensions
kOfxParamTypeInteger2D - integer property of two dimensions
kOfxParamTypeDouble3D - double property of three dimensions
kOfxParamTypeInteger3D - integer property of three dimensions
kOfxParamTypeString - string property of one dimension
kOfxParamTypeCustom - string property of one dimension
kOfxParamTypeGroup - does not have this property
kOfxParamTypePage - does not have this property
kOfxParamTypePushButton - does not have this property
-
kOfxParamPropDoubleType
Describes how the double parameter should be interpreted by a host.
Type - C string X 1
Default - kOfxParamDoubleTypePlain
Property Set - 1D, 2D and 3D float plugin parameter descriptor (read/write) and instance (read only),
Valid Values -This must be one of
kOfxParamDoubleTypePlain - parameter has no special interpretation,
kOfxParamDoubleTypeAngle - parameter is to be interpretted as an angle,
kOfxParamDoubleTypeScale - parameter is to be interpretted as a scale factor,
kOfxParamDoubleTypeTime - parameter represents a time value (1D only),
kOfxParamDoubleTypeAbsoluteTime - parameter represents an absolute time value (1D only),
kOfxParamDoubleTypeX - size wrt to the project’s X dimension (1D only), in canonical coordinates,
kOfxParamDoubleTypeXAbsolute - absolute position on the X axis (1D only), in canonical coordinates,
kOfxParamDoubleTypeY - size wrt to the project’s Y dimension(1D only), in canonical coordinates,
kOfxParamDoubleTypeYAbsolute - absolute position on the Y axis (1D only), in canonical coordinates,
kOfxParamDoubleTypeXY - size in 2D (2D only), in canonical coordinates,
kOfxParamDoubleTypeXYAbsolute - an absolute position on the image plane, in canonical coordinates.
Double parameters can be interpreted in several different ways, this property tells the host how to do so and thus gives hints as to the interface of the parameter.
-
kOfxParamDoubleTypePlain
value for the kOfxParamPropDoubleType property, indicating the parameter has no special interpretation and should be interpretted as a raw numeric value.
-
kOfxParamDoubleTypeScale
value for the kOfxParamPropDoubleType property, indicating the parameter is to be interpreted as a scale factor. See kOfxParamPropDoubleType.
-
kOfxParamDoubleTypeAngle
value for the kOfxParamDoubleTypeAngle property, indicating the parameter is to be interpreted as an angle. See kOfxParamPropDoubleType.
-
kOfxParamDoubleTypeTime
value for the kOfxParamDoubleTypeAngle property, indicating the parameter is to be interpreted as a time. See kOfxParamPropDoubleType.
-
kOfxParamDoubleTypeAbsoluteTime
value for the kOfxParamDoubleTypeAngle property, indicating the parameter is to be interpreted as an absolute time from the start of the effect. See kOfxParamPropDoubleType.
-
kOfxParamDoubleTypeX
value for the kOfxParamPropDoubleType property, indicating a size in canonical coords in the X dimension. See kOfxParamPropDoubleType.
-
kOfxParamDoubleTypeY
value for the kOfxParamPropDoubleType property, indicating a size in canonical coords in the Y dimension. See kOfxParamPropDoubleType.
-
kOfxParamDoubleTypeXAbsolute
value for the kOfxParamPropDoubleType property, indicating an absolute position in canonical coords in the X dimension. See kOfxParamPropDoubleType.
-
kOfxParamDoubleTypeYAbsolute
value for the kOfxParamPropDoubleType property, indicating an absolute position in canonical coords in the Y dimension. See kOfxParamPropDoubleType.
-
kOfxParamDoubleTypeXY
value for the kOfxParamPropDoubleType property, indicating a 2D size in canonical coords. See kOfxParamPropDoubleType.
-
kOfxParamDoubleTypeXYAbsolute
value for the kOfxParamPropDoubleType property, indicating a 2D position in canonical coords. See kOfxParamPropDoubleType.
-
kOfxParamPropDefaultCoordinateSystem
Describes in which coordinate system a spatial double parameter’s default value is specified.
Type - C string X 1
Default - kOfxParamCoordinatesCanonical
Property Set - Non normalised spatial double parameters, ie: any double param who’s kOfxParamPropDoubleType is set to one of…
kOfxParamDoubleTypeX
kOfxParamDoubleTypeXAbsolute
kOfxParamDoubleTypeY
kOfxParamDoubleTypeYAbsolute
kOfxParamDoubleTypeXY
kOfxParamDoubleTypeXYAbsolute
Valid Values - This must be one of
kOfxParamCoordinatesCanonical - the default is in canonical coords
kOfxParamCoordinatesNormalised - the default is in normalised coordinates
This allows a spatial param to specify what its default is, so by saying normalised and “0.5” it would be in the ‘middle’, by saying canonical and 100 it would be at value 100 independent of the size of the image being applied to.
-
kOfxParamCoordinatesCanonical
Define the canonical coordinate system.
-
kOfxParamCoordinatesNormalised
Define the normalised coordinate system.
-
kOfxParamPropHasHostOverlayHandle
A flag to indicate if there is a host overlay UI handle for the given parameter.
Type - int x 1
Property Set - plugin parameter descriptor (read only)
Valid Values - 0 or 1
If set to 1, then the host is flagging that there is some sort of native user overlay interface handle available for the given parameter.
-
kOfxParamPropUseHostOverlayHandle
A flag to indicate that the host should use a native UI overlay handle for the given parameter.
Type - int x 1
Property Set - plugin parameter descriptor (read/write only) and instance (read only)
Default - 0
Valid Values - 0 or 1
If set to 1, then a plugin is flaging to the host that the host should use a native UI overlay handle for the given parameter. A plugin can use this to keep a native look and feel for parameter handles. A plugin can use kOfxParamPropHasHostOverlayHandle to see if handles are available on the given parameter.
-
kOfxParamPropShowTimeMarker
Enables the display of a time marker on the host’s time line to indicate the value of the absolute time param.
Type - int x 1
Property Set - plugin parameter descriptor (read/write) and instance (read/write)
Default - 0
Valid Values - 0 or 1
If a double parameter is has kOfxParamPropDoubleType set to kOfxParamDoubleTypeAbsoluteTime, then this indicates whether any marker should be made visible on the host’s time line.
-
kOfxPluginPropParamPageOrder
Sets the parameter pages and order of pages.
Type - C string X N
Property Set - plugin parameter descriptor (read/write) and instance (read only)
Default - “”
Valid Values - the names of any page param in the plugin
This property sets the preferred order of parameter pages on a host. If this is never set, the preferred order is the order the parameters were declared in.
-
kOfxParamPropPageChild
The names of the parameters included in a page parameter.
Type - C string X N
Property Set - plugin parameter descriptor (read/write) and instance (read only)
Default - “”
Valid Values - the names of any parameter that is not a group or page, as well as kOfxParamPageSkipRow and kOfxParamPageSkipColumn
This is a property on parameters of type kOfxParamTypePage, and tells the page what parameters it contains. The parameters are added to the page from the top left, filling in columns as we go. The two pseudo param names kOfxParamPageSkipRow and kOfxParamPageSkipColumn are used to control layout.
Note parameters can appear in more than one page.
-
kOfxParamPropParent
The name of a parameter’s parent group.
Type - C string X 1
Property Set - plugin parameter descriptor (read/write) and instance (read only),
Default - “”, which implies the “root” of the hierarchy,
Valid Values - the name of a parameter with type of kOfxParamTypeGroup
Hosts that have hierarchical layouts of their params use this to recursively group parameter.
By default parameters are added in order of declaration to the ‘root’ hierarchy. This property is used to reparent params to a predefined param of type kOfxParamTypeGroup.
-
kOfxParamPropGroupOpen
Whether the initial state of a group is open or closed in a hierarchical layout.
Type - int X 1
Property Set - plugin parameter descriptor (read/write) and instance (read only)
Default - 1
Valid Values - 0 or 1
This is a property on parameters of type kOfxParamTypeGroup, and tells the group whether it should be open or closed by default.
-
kOfxParamPropEnabled
Used to enable a parameter in the user interface.
Type - int X 1
Property Set - plugin parameter descriptor (read/write) and instance (read/write),
Default - 1
Valid Values - 0 or 1
When set to 0 a user should not be able to modify the value of the parameter. Note that the plug-in itself can still change the value of a disabled parameter.
-
kOfxParamPropDataPtr
A private data pointer that the plug-in can store its own data behind.
Type - pointer X 1
Property Set - plugin parameter instance (read/write),
Default - NULL
This data pointer is unique to each parameter instance, so two instances of the same parameter do not share the same data pointer. Use it to hang any needed private data structures.
-
kOfxParamPropChoiceOption
Set options of a choice parameter.
Type - UTF8 C string X N
Property Set - plugin parameter descriptor (read/write) and instance (read/write),
Default - the property is empty with no options set.
This property contains the set of options that will be presented to a user from a choice parameter. See ParametersChoice for more details.
-
kOfxParamPropChoiceOrder
Set values the host should store for a choice parameter.
Type - int X N
Property Set - plugin parameter descriptor (read/write) and instance (read/write),
Default - Zero-based ordinal list of same length as
OfxParamPropChoiceOption
This property specifies the order in which the options are presented. See “Choice Parameters” for more details. This property is optional; if not set, the host will present the options in their natural order.
This property is useful when changing order of choice param options, or adding new options in the middle, in a new version of the plugin.
Plugin v1: Option = {"OptA", "OptB", "OptC"} Order = {1, 2, 3} Plugin v2: // will be shown as OptA / OptB / NewOpt / OptC Option = {"OptA", "OptB", "OptC", NewOpt"} Order = {1, 2, 4, 3}
Note that this only affects the host UI’s display order; the project still stores the index of the selected option as always. Plugins should never reorder existing options if they desire backward compatibility.
Values may be arbitrary 32-bit integers. Behavior is undefined if the same value occurs twice in the list; plugins should not do that.
- Since
Version 1.5
-
kOfxParamPropChoiceEnum
Set a enumeration string in a StrChoice (string-valued choice) parameter.
Type - UTF8 C string X N
Property Set - plugin parameter descriptor (read/write) and instance (read/write),
Default - the property is empty with no options set.
This property contains the set of enumeration strings stored by the host in the project corresponding to the options that will be presented to a user from a StrChoice parameter. See ParametersChoice for more details.
- Since
Version 1.5
-
kOfxParamHostPropSupportsStrChoiceAnimation
Indicates if the host supports animation of string choice params.
Type - int X 1
Property Set - host descriptor (read only)
Valid Values - 0 or 1
- Since
Version 1.5
-
kOfxParamHostPropSupportsStrChoice
Indicates if the host supports the StrChoice param type.
Type - int X 1
Property Set - host descriptor (read only)
Valid Values - 0 or 1
- Since
Version 1.5
-
kOfxParamPropMin
The minimum value for a numeric parameter.
Type - int or double X N
Property Set - plugin parameter descriptor (read/write) and instance (read/write),
Default - the smallest possible value corresponding to the parameter type (eg: INT_MIN for an integer, -DBL_MAX for a double parameter)
Setting this will also reset kOfxParamPropDisplayMin.
-
kOfxParamPropMax
The maximum value for a numeric parameter.
Type - int or double X N
Property Set - plugin parameter descriptor (read/write) and instance (read/write),
Default - the largest possible value corresponding to the parameter type (eg: INT_MAX for an integer, DBL_MAX for a double parameter)
Setting this will also reset :;kOfxParamPropDisplayMax.
-
kOfxParamPropDisplayMin
The minimum value for a numeric parameter on any user interface.
Type - int or double X N
Property Set - plugin parameter descriptor (read/write) and instance (read/write),
Default - the smallest possible value corresponding to the parameter type (eg: INT_MIN for an integer, -DBL_MAX for a double parameter)
If a user interface represents a parameter with a slider or similar, this should be the minumum bound on that slider.
-
kOfxParamPropDisplayMax
The maximum value for a numeric parameter on any user interface.
Type - int or double X N
Property Set - plugin parameter descriptor (read/write) and instance (read/write),
Default - the largest possible value corresponding to the parameter type (eg: INT_MAX for an integer, DBL_MAX for a double parameter)
If a user interface represents a parameter with a slider or similar, this should be the maximum bound on that slider.
-
kOfxParamPropIncrement
The granularity of a slider used to represent a numeric parameter.
Type - double X 1
Property Set - plugin parameter descriptor (read/write) and instance (read/write),
Default - 1
Valid Values - any greater than 0.
This value is always in canonical coordinates for double parameters that are normalised.
-
kOfxParamPropDigits
How many digits after a decimal point to display for a double param in a GUI.
Type - int X 1
Property Set - plugin parameter descriptor (read/write) and instance (read/write),
Default - 2
Valid Values - any greater than 0.
This applies to double params of any dimension.
-
kOfxParamPropDimensionLabel
Label for individual dimensions on a multidimensional numeric parameter.
Type - UTF8 C string X 1
Property Set - plugin parameter descriptor (read/write) and instance (read only),
Default - “x”, “y” and “z”
Valid Values - any
Use this on 2D and 3D double and integer parameters to change the label on an individual dimension in any GUI for that parameter.
-
kOfxParamPropIsAutoKeying
Will a value change on the parameter add automatic keyframes.
Type - int X 1
Property Set - plugin parameter instance (read only),
Valid Values - 0 or 1
This is set by the host simply to indicate the state of the property.
-
kOfxParamPropCustomInterpCallbackV1
A pointer to a custom parameter’s interpolation function.
Type - pointer X 1
Property Set - plugin parameter descriptor (read/write) and instance (read only),
Default - NULL
Valid Values - must point to a OfxCustomParamInterpFuncV1
It is an error not to set this property in a custom parameter during a plugin’s define call if the custom parameter declares itself to be an animating parameter.
-
kOfxParamPropStringMode
Used to indicate the type of a string parameter.
Type - C string X 1
Property Set - plugin string parameter descriptor (read/write) and instance (read only),
Default - kOfxParamStringIsSingleLine
Valid Values - This must be one of the following
-
kOfxParamPropStringFilePathExists
Indicates string parameters of file or directory type need that file to exist already.
Type - int X 1
Property Set - plugin string parameter descriptor (read/write) and instance (read only),
Default - 1
Valid Values - 0 or 1
If set to 0, it implies the user can specify a new file name, not just a pre-existing one.
-
kOfxParamStringIsSingleLine
Used to set a string parameter to be single line, value to be passed to a kOfxParamPropStringMode property.
-
kOfxParamStringIsMultiLine
Used to set a string parameter to be multiple line, value to be passed to a kOfxParamPropStringMode property.
-
kOfxParamStringIsFilePath
Used to set a string parameter to be a file path, value to be passed to a kOfxParamPropStringMode property.
-
kOfxParamStringIsDirectoryPath
Used to set a string parameter to be a directory path, value to be passed to a kOfxParamPropStringMode property.
-
kOfxParamStringIsLabel
Use to set a string parameter to be a simple label, value to be passed to a kOfxParamPropStringMode property
-
kOfxParamStringIsRichTextFormat
String value on the kOfxParamPropStringMode property of a string parameter (added in 1.3)
-
kOfxParamPropCustomValue
Used by interpolating custom parameters to get and set interpolated values.
Type - C string X 1 or 2
This property is on the inArgs property and outArgs property of a OfxCustomParamInterpFuncV1 and in both cases contains the encoded value of a custom parameter. As an inArgs property it will have two values, being the two keyframes to interpolate. As an outArgs property it will have a single value and the plugin should fill this with the encoded interpolated value of the parameter.
-
kOfxParamPropInterpolationTime
Used by interpolating custom parameters to indicate the time a key occurs at.
Type - double X 2
Property Set - inArgs parameter of a OfxCustomParamInterpFuncV1 (read only)
The two values indicate the absolute times the surrounding keyframes occur at. The keyframes are encoded in a kOfxParamPropCustomValue property.
-
kOfxParamPropInterpolationAmount
Property used by OfxCustomParamInterpFuncV1 to indicate the amount of interpolation to perform.
Type - double X 1
Property Set - inArgs parameter of a OfxCustomParamInterpFuncV1 (read only)
Valid Values - from 0 to 1
This property indicates how far between the two kOfxParamPropCustomValue keys to interpolate.
Typedefs
-
typedef struct OfxParamStruct *OfxParamHandle
Blind declaration of an OFX param.
-
typedef struct OfxParamSetStruct *OfxParamSetHandle
Blind declaration of an OFX parameter set.
- OfxStatus() OfxCustomParamInterpFuncV1 (OfxParamSetHandle instance, OfxPropertySetHandle inArgs, OfxPropertySetHandle outArgs)
Function prototype for custom parameter interpolation callback functions.
instance
the plugin instance that this parameter occurs ininArgs
handle holding the following properties…kOfxPropName - the name of the custom parameter to interpolate
kOfxPropTime - absolute time the interpolation is ocurring at
kOfxParamPropCustomValue - string property that gives the value of the two keyframes to interpolate, in this case 2D
kOfxParamPropInterpolationTime - 2D double property that gives the time of the two keyframes we are interpolating
kOfxParamPropInterpolationAmount - 1D double property indicating how much to interpolate between the two keyframes
outArgs
handle holding the following properties to be setkOfxParamPropCustomValue - the value of the interpolated custom parameter, in this case 1D
The plugin needs to parse the two strings encoding keyframes on either side of the time we need a value for. It should then interpolate a new value for it, encode it into a string and set the kOfxParamPropCustomValue property with this on the outArgs handle.
The interp value is a linear interpolation amount, however his may be derived from a cubic (or other) curve.
-
typedef struct OfxParameterSuiteV1 OfxParameterSuiteV1
The OFX suite used to define and manipulate user visible parameters.
-
struct OfxParameterSuiteV1
- #include <ofxParam.h>
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)