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.

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

kOfxParamPropDoubleType

Describes how the double parameter should be interpreted by a host.

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.

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.

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.

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 in

  • inArgs 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 set

    • kOfxParamPropCustomValue - the value of the interpolated custom parameter, in this case 1D

This function allows custom parameters to animate by performing interpolation between keys.

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 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: