Effect Parameters
=================

Introduction
------------

Nearly all plug-ins have some sort of parameters that control their
behaviour, the radius of a circle drawer, the frequencies to filter out
of an audio signal, the colour of a lens flare and so on.

Seeing as hosts already provide for the general management of their own
native parameters (eg: persistance, interface, animation etc...), it
would make no sense to force plug-ins to do this all themselves.

The OFX Parameters Suite is the means by which parameters are defined
and used by the plug-in but maintained by the host. It is defined in the
ofxParam.h header file.

Note that the entire state of the plugin is encoded in the value of its
parameter set. If you need to persist some sort of private data, you
must do so by setting param values in the effects. The :c:macro:`kOfxActionSyncPrivateData`
is an action that tells you
when to flush any values that need persisting out to the effects param
set. You can reconstruct your private data during the :c:macro:`kOfxActionCreateInstance`.

Defining Parameters
-------------------

A plugin needs to define it's parameters during a describe action. It
does this with the
:cpp:func:`OfxParameterSuiteV1::paramDefine`
function, which returns a handle to a parameter *description*.
Parameters cannot currently be defined outside of the plugins describe
actions.

Parameters are uniquely labelled within a plugin with an ASCII null
terminated C-string. This name is not necassarily meant to be end-user
readable, various properties are provided to set the user visible labels
on the param.

All parameters hold properties, though the exact set of properties on a
parameter is dependant on the type of the parameter.

A parameter's handle comes in two slightly different flavours. The
handle returned inside a plugin's describe action is not an actual
instance of a parameter, it is there for the purpose description only.
You can only set properties on that handle (eg: label, min/max value,
default ...), you cannot get values from it or set values in it. The
parameters defined in the describe action will common to all instances
of a plugin.

The handle returned by
:cpp:func:`OfxParameterSuiteV1::paramGetHandle`
outside of a describe action will be a working instance of a parameter,
you can still set (some) properties of the parameter, and all the
get/set value functions are now useable.

.. _parameterTypes:

Parameter Types
---------------

There are seventeen types of parameter. These are

* .. doxygendefine:: kOfxParamTypeInteger
* .. doxygendefine:: kOfxParamTypeInteger2D
* .. doxygendefine:: kOfxParamTypeInteger3D
* .. doxygendefine:: kOfxParamTypeDouble
* .. doxygendefine:: kOfxParamTypeDouble2D
* .. doxygendefine:: kOfxParamTypeDouble3D
* .. doxygendefine:: kOfxParamTypeRGB
* .. doxygendefine:: kOfxParamTypeRGBA
* .. doxygendefine:: kOfxParamTypeBoolean
* .. doxygendefine:: kOfxParamTypeChoice
* .. doxygendefine:: kOfxParamTypeString
* .. doxygendefine:: kOfxParamTypeCustom
* .. doxygendefine:: kOfxParamTypePushButton
* .. doxygendefine:: kOfxParamTypeGroup
* .. doxygendefine:: kOfxParamTypePage
* .. doxygendefine:: kOfxParamTypeParametric


Multidimensional Parameters
---------------------------

Some parameter types are multi dimensional, these are...

-  :c:macro:`kOfxParamTypeDouble2D`

-  :c:macro:`kOfxParamTypeInteger2D`

-  :c:macro:`kOfxParamTypeDouble3D`

-  :c:macro:`kOfxParamTypeInteger3D`

-  :c:macro:`kOfxParamTypeRGB`

-  :c:macro:`kOfxParamTypeRGBA`

-  :c:macro:`kOfxParamTypeParametric`


These parameters are treated in an atomic manner, so that all dimensions
are set/retrieved simultaneously. This applies to keyframes as well.

The non colour parameters have an implicit 'X', 'Y' and 'Z' dimension,
and any interface should display them with such labels.


Integer Parameters
------------------

These are typed by :c:macro:`kOfxParamTypeInteger`, :c:macro:`kOfxParamTypeInteger2D`
and :c:macro:`kOfxParamTypeInteger3D`.

Integer parameters are of 1, 2 and 3D varieties and contain integer
values, between INT_MIN and INT_MAX.

Double Parameters
-----------------

These are typed by :c:macro:`kOfxParamTypeDouble`, :c:macro:`kOfxParamTypeDouble2D`
and :c:macro:`kOfxParamTypeDouble3D`.

Double parameters are of 1, 2 and 3D varieties and contain double
precision floating point values.


Colour Parameters
-----------------

These are typed by :c:macro:`kOfxParamTypeRGB` and :c:macro:`kOfxParamTypeRGBA`.

Colour parameters are 3 or 4 dimensional double precision floating point
parameters. They are displayed using the host's appropriate interface
for a colour. Values are always normalised in the range [0 .. 1], with 0
being the nominal black point and 1 being the white point.


Boolean Parameters
------------------

This is typed by :c:macro:`kOfxParamTypeBoolean`.

Boolean parameters are integer values that can have only one of two
values, 0 or 1.


Choice Parameters
-----------------

This is typed by :c:macro:`kOfxParamTypeChoice`.

Choice parameters are integer values from 0 to N-1, which correspond to
N labeled options.

Choice parameters have their individual options set via the
:c:macro:`kOfxParamPropChoiceOption` property,
for example

    ::

        gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, 0, "1st Choice");
        gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, 1, "2nd Choice");
        gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, 2, "3nd Choice");
        ...
        gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, n, "nth Choice");

It is an error to have gaps in the choices after the describe action has
returned.


String Parameters
-----------------

This is typed by :c:macro:`kOfxParamTypeString`.

String parameters contain null terminated ``char *`` UTF8 C strings.
They can be of several different variants, which is controlled by the
:c:macro:`kOfxParamPropStringMode` property,
these are

-  .. doxygendefine:: kOfxParamStringIsSingleLine

-  .. doxygendefine:: kOfxParamStringIsMultiLine

-  .. doxygendefine:: kOfxParamStringIsFilePath

-  .. doxygendefine:: kOfxParamStringIsDirectoryPath

-  .. doxygendefine:: kOfxParamStringIsLabel

Group Parameters
----------------

This is typed by :c:macro:`kOfxParamTypeGroup`.

Group parameters allow all parameters to be arranged in a tree
hierarchy. They have no value, they are purely a grouping element.

All parameters have a :c:macro:`kOfxParamPropParent`
property, which is a string property naming the group parameter which is
its parent.

The empty string "" is used to label the root of the parameter
hierarchy, which is the default parent for all parameters.

Parameters inside a group are ordered by their order of addition to that
group, which implies parameters in the root group are added in order of
definition.

Any host based hierarchical GUI should use this hierarchy to order
parameters (eg: animation sheets).

Page Parameters
---------------

This is typed by :c:macro:`kOfxParamTypePage`.

Page parameters are covered in detail in their own
:ref:`section. <ParametersInterfacesPagedLayouts>`

Custom Parameters
-----------------

This is typed by :c:macro:`kOfxParamTypeCustom`.

Custom parameters contain null terminated char \* C strings, and may
animate. They are designed to provide plugins with a way of storing data
that is too complicated or impossible to store in a set of ordinary
parameters.

If a custom parameter animates, it must set its
:c:macro:`kOfxParamPropCustomInterpCallbackV1`
property, which points to a function with the following signature:

.. doxygentypedef:: OfxCustomParamInterpFuncV1

This function is used to interpolate keyframes in custom params.

Custom parameters have no interface by default. However,

-  if they animate, the host's animation sheet/editor should present a
   keyframe/curve representation to allow positioning of keys and
   control of interpolation. The 'normal' (ie: paged or hierarchical)
   interface should not show any gui.
-  if the custom param sets its
   kOfxParamPropInteractV1
   property, this should be used by the host in any normal (ie: paged or
   hierarchical) interface for the parameter.

Custom parameters are mandatory, as they are simply ASCII C strings.
However, animation of custom parameters an support for an in editor
interact is optional.

.. kOfxParamTypePushButton:

Push Button Parameters
----------------------

This is typed by :c:macro:`kOfxParamTypePushButton`.

Push button parameters have no value, they are there so a plugin can
detect if they have been pressed and perform some action. If pressed, a
:c:macro:`kOfxActionInstanceChanged`  action
will be issued on the parameter with a
:c:macro:`kOfxPropChangeReason` of
:c:macro:`kOfxChangeUserEdited`.

Animation
---------

By default the following parameter types animate...

-  :c:macro:`kOfxParamTypeInteger`
-  :c:macro:`kOfxParamTypeInteger2D`
-  :c:macro:`kOfxParamTypeInteger3D`
-  :c:macro:`kOfxParamTypeDouble`
-  :c:macro:`kOfxParamTypeDouble2D`
-  :c:macro:`kOfxParamTypeDouble3D`
-  :c:macro:`kOfxParamTypeRGBA`
-  :c:macro:`kOfxParamTypeRGB`

The following types cannot animate...

-  :c:macro:`kOfxParamTypeGroup`
-  :c:macro:`kOfxParamTypePage`
-  :c:macro:`kOfxParamTypePushButton`

The following may animate, depending on the host. Properties exist on
the host to check this. If the host does support animation on them, then
they do **not** animate by default. They are...

-  :c:macro:`kOfxParamTypeCustom`
-  :c:macro:`kOfxParamTypeString`
-  :c:macro:`kOfxParamTypeBoolean`
-  :c:macro:`kOfxParamTypeChoice`

By default the
:cpp:func:`OfxParameterSuiteV1::paramGetValue`
will get the 'current' value of the parameter. To access values in a
potentially animating parameter, use the
:cpp:func:`OfxParameterSuiteV1::paramGetValueAtTime` function.

Keys can be manipulated in a parameter using a variety of functions,
these are...

-  :cpp:func:`OfxParameterSuiteV1::paramSetValueAtTime`
-  :cpp:func:`OfxParameterSuiteV1::paramGetNumKeys`
-  :cpp:func:`OfxParameterSuiteV1::paramGetKeyTime`
-  :cpp:func:`OfxParameterSuiteV1::paramGetKeyIndex`
-  :cpp:func:`OfxParameterSuiteV1::paramDeleteKey`
-  :cpp:func:`OfxParameterSuiteV1::paramDeleteAllKeys`


Parameter Interfaces
--------------------

Parameters will be presented to the user in some form of interface.
Typically on most host systems, this comes in three varieties...

-  a paged layout, with parameters spread over multiple controls pages
   (eg: the FLAME control pages)
-  a hierarchical layout, with parameters presented in a grouped tree
   (eg: the After Effects 'effects' window)
-  an animation sheet, showing animation curves and key frames.
   Typically this is hierarchical.

Most systems have an animation sheet and present one of either the paged
or the hierarchical layouts.

Because a hierarchy of controls is explicitly set during plugin
definition, the case of the animation sheet and hierarchial GUIs are
taken care of explicitly.

.. _ParametersInterfacesPagedLayouts:

Paged Parameter Editors
-----------------------

A paged layout of controls is difficult to standardise, as the size of
the page and controls, how the controls are positioned on the page, how
many controls appear on a page etc... depend very much upon the host
implementation. A paged layout is ideally best described in the .XML
resource supplied by the plugin, however a fallback page layout can be
specified in OFX via the :c:macro:`kOfxParamTypePage` parameter type.

Several host properties are associated with paged layouts, these are...

-  :c:macro:`kOfxParamHostPropMaxPages`
   The maximum number of pages you may use, 0 implies an unpaged
   layout
-  :c:macro:`kOfxParamHostPropPageRowColumnCount`
   The number of rows and columns for parameters in the paged layout.

Each page parameter represents a page of controls. The controls in that
page are set by the plugin using the :c:macro:`kOfxParamPropPageChild`
multi-dimensional string. For example...

    ::

        OfxParamHandle  page;
        gHost->paramDefine(plugin, kOfxParamTypePage, "Main", &page);
              
        propHost->propSetString(page, kOfxParamPropPageChild, 0, "size");      // add the size parameter to the top left of the page
        propHost->propSetString(page, kOfxParamPropPageChild, 1, kOfxParamPageSkipRow); // skip a row
        propHost->propSetString(page, kOfxParamPropPageChild, 2, "centre");    // add the centre parameter
        propHost->propSetString(page, kOfxParamPropPageChild, 3, kOfxParamPageSkipColumn); // skip a column, we are now at the top of the next column
        propHost->propSetString(page, kOfxParamPropPageChild, 4, "colour"); // add the colour parameter 

The host then places the parameters on that page in the order they were
added, starting at the top left and going down columns, then across rows
as they fill.

Note that there are two pseudo parameters names used to help control
layout:

.. doxygendefine:: kOfxParamPageSkipRow
.. doxygendefine:: kOfxParamPageSkipColumn

These will help control how parameters are added to a page, allowing
vertical or horizontal slots to be skipped.

A host sets the order of pages by using the instance's
:c:macro:`kOfxPluginPropParamPageOrder` property.
Note that this property can vary from context to context, so
you can exclude pages in contexts they are not useful in. For example...

    ::

        OfxStatus describeInContext(OfxImageEffectHandle plugin)
        {
        ...
            // order our pages of controls
            propHost->propSetString(paramSetProp, kOfxPluginPropParamPageOrder, 0, "Main");
            propHost->propSetString(paramSetProp, kOfxPluginPropParamPageOrder, 1, "Sampling");
            propHost->propSetString(paramSetProp, kOfxPluginPropParamPageOrder, 2, "Colour Correction");
            if(isGeneralContext)
               propHost->propSetString(paramSetProp, kOfxPluginPropParamPageOrder, 3, "Dance! Dance! Dance!");
        ...
        } 

.. note::
   Parameters can be placed on more than a single page (this is often useful).
   Group parameters cannot be added to a page.
   Page parameters cannot be added to a page or group.

Instance changed callback
-------------------------

Whenever a parameter's value changes, the host is expected to issue a call to
the :c:macro:`kOfxActionInstanceChanged` action with the name of the parameter
that changed and a reason indicating who triggered the change:

.. doxygendefine:: kOfxChangeUserEdited

.. doxygendefine:: kOfxChangePluginEdited

.. doxygendefine:: kOfxChangeTime

.. ParametersInterfacesUndoRedo:

Parameter Undo/Redo
-------------------

Hosts usually retain an undo/redo stack, so users can undo changes they
make to a parameter. Often undos and redos are grouped together into an
undo/redo block, where multiple parameters are dealt with as a single
undo/redo event. Plugins need to be able to deal with this cleanly.

Parameters can be excluded from being undone/redone if they set the
:c:macro:`kOfxParamPropCanUndo` property to 0.

If the plugin changes parameters values by calling the get and set
value functions, they will ordinarily be put on the undo stack, one
event per parameter that is changed. If the plugin wants to group sets
of parameter changes into a single undo block and label that block, it
should use the
:cpp:func:`OfxParameterSuiteV1::paramEditBegin`
and
:cpp:func:`OfxParameterSuiteV1::paramEditEnd`
functions.

An example would be a 'preset' choice parameter in a sky simulation
whose job is to set other parameters to values that achieve certain
looks, eg "Dusk", "Midday", "Stormy", "Night" etc... This parameter has
a value change callback which looks for :c:macro:`kOfxChangeUserEdited`
then sets other parameters, sky colour, cloud density, sun position
etc.... It also resets itself to the first choice, which says "Example
Skys...".

Rather than have many undo events appear on the undo stack for each
individual parameter change, the effect groups them via the
paramEditBegin/paramEditEnd and gets a single undo event. The 'preset'
parameter would also not want to be undoable as it such an event is
redunant. Note that as the 'preset' has been changed it will be sent
another instance changed action, however it will have a reason of
:c:macro:`kOfxChangePluginEdited`, which it ignores and so stops an infinite
loop occuring.

.. ParametersXML:

XML Resource Specification for Parameters
-----------------------------------------

Parameters can have various properties overriden via a seperate XML
based resource file.

.. ParametersPersistance:

Parameter Persistance
---------------------

All parameters flagged with the
:c:macro:`kOfxParamPropPersistant` property will
persist when an effect is saved. How the effect is saved is completely
up to the host, it may be in a file, a data base, where ever. We call a
saved set of parameters a *setup*. A host will need to save the major
version number of the plugin, as well as the plugin's unique identifier,
in any setup.

When an host loads a set up it should do so in the following manner...

1. examines the setup for the major version number.
2. find a matching plugin with that major version number, if multiple
   minor versions exist, the plugin with the largest minor version
   should be used.
3. creates an instance of that plugin with its set of parameters.
4. sets all those parameters to the defaults specified by the plugin.
5. examines the setup for any persistant parameters, then sets the
   instance's parameters to any found in it.
6. calls create instance on the plugin.

It is *not* an error for a parameter to exist in the plugin but not the
setup, and vice versa. This allows a plugin developer to modify
parameter sets between point releases, generally by adding new params.
The developer should be sure that the default values of any new
parameters yield the same behaviour as before they were added, otherwise
it would be a breach of the 'major version means compatibility' rule.

.. ParameterPropertiesVariantTypes:

Parameter Properties Whose Type Vary
------------------------------------

Some properties type depends on the kind of the parameter, eg:
:c:macro:`kOfxParamPropDefault` is an int for a
integer parameter but a double X 2 for a :c:macro:`kOfxParamTypeDouble2D`
parameter.

The variant property types are as follows....

-  :c:macro:`kOfxParamTypeInteger`
    int X 1
-  :c:macro:`kOfxParamTypeDouble`
    double X 1
-  :c:macro:`kOfxParamTypeBoolean`
    int X 1
-  :c:macro:`kOfxParamTypeChoice`
    int X 1
-  :c:macro:`kOfxParamTypeRGBA`
    double X 4 (normalised to 0..1 range)
-  :c:macro:`kOfxParamTypeRGB`
    double X 3 (normalised to 0..1 range)
-  :c:macro:`kOfxParamTypeDouble2D`
    double X 2
-  :c:macro:`kOfxParamTypeInteger2D`
    int X 2
-  :c:macro:`kOfxParamTypeDouble3D`
    double X 3
-  :c:macro:`kOfxParamTypeInteger3D`
    int X 3
-  :c:macro:`kOfxParamTypeString`
    char \* X 1
-  :c:macro:`kOfxParamTypeCustom`
    char \* X 1
-  :c:macro:`kOfxParamTypePushButton`
    none

.. ParameterPropertiesDoubleTypes:

Types of Double Parameters
--------------------------

Double parameters can be used to represent a variety of data, by
flagging what a double parameter is representing, a plug-in allows a
host to represent to the user a more appropriate interface than a raw
numerical value. Double parameters have the
:c:macro:`kOfxParamPropDoubleType` property,
which gives some meaning to the value. This can be one of...

-  .. doxygendefine:: kOfxParamDoubleTypePlain

-  .. doxygendefine:: kOfxParamDoubleTypeAngle

-  .. doxygendefine:: kOfxParamDoubleTypeScale

-  .. doxygendefine:: kOfxParamDoubleTypeTime

-  .. doxygendefine:: kOfxParamDoubleTypeAbsoluteTime

-  .. doxygendefine:: kOfxParamDoubleTypeX

-  .. doxygendefine:: kOfxParamDoubleTypeXAbsolute

-  .. doxygendefine:: kOfxParamDoubleTypeY

-  .. doxygendefine:: kOfxParamDoubleTypeYAbsolute

-  .. doxygendefine:: kOfxParamDoubleTypeXY

-  .. doxygendefine:: kOfxParamDoubleTypeXYAbsolute

-  .. doxygendefine:: kOfxParamDoubleTypeNormalisedX

-  .. doxygendefine:: kOfxParamDoubleTypeNormalisedXAbsolute

-  .. doxygendefine:: kOfxParamDoubleTypeNormalisedY

-  .. doxygendefine:: kOfxParamDoubleTypeNormalisedYAbsolute

-  .. doxygendefine:: kOfxParamDoubleTypeNormalisedXY

-  .. doxygendefine:: kOfxParamDoubleTypeNormalisedXYAbsolute


Plain Double Parameters
-----------------------

Double parameters with their
:c:macro:`kOfxParamPropDoubleType` property set
to :c:macro:`kOfxParamDoubleTypePlain` are uninterpretted. The values
represented to the user are what is reported back to the effect when
values are retrieved. 1, 2 and 3D parameters can be flagged as
:c:macro:`kOfxParamDoubleTypePlain`, which is the default.

For example a physical simulation plugin might have a 'mass' double
parameter, which is in kilograms, which should be displayed and used as
a raw value.


Angle Double Parameters
-----------------------

Double parameters with their
:c:macro:`kOfxParamPropDoubleType` property set
to :c:macro:`kOfxParamDoubleTypeAngle` are interpretted as angles. The host
could use some fancy angle widget in it's interface, representing
degrees, angles mils whatever. However, the values returned to a plugin
are always in degrees. Applicable to 1, 2 and 3D parameters.

For example a plugin that rotates an image in 3D would declare a 3D
double parameter and flag that as an angle parameter and use the values
as Euler angles for the rotation.

Scale Double Parameters
-----------------------

Double parameters with their
:c:macro:`kOfxParamPropDoubleType` property set
to :c:macro:`kOfxParamDoubleTypeScale` are interpretted as scale factors. The
host can represent these as 1..100 percentages, 0..1 scale factors,
fractions or whatever is appropriate for its interface. However, the
plugin sees these as a straight scale factor, in the 0..1 range.
Applicable to 1, 2 and 3D parameters.

For example a plugin that scales the size of an image would declare a
'image scale' parameter and use the raw value of that to scale the
image.


Time Double Parameters
----------------------

Double parameters with their
:c:macro:`kOfxParamPropDoubleType` property set
to :c:macro:`kOfxParamDoubleTypeTime` are interpretted as a time. The host can
represent these as frames, seconds, milliseconds, millenia or whatever
it feels is appropriate. However, a visual effect plugin sees such
values in 'frames'. Applicable only to 1D double parameters. It is an
error to set this on any other type of double parameter.

For example a plugin that does motion blur would have a 'shutter time'
parameter and flags that as a time parameter. The value returned would
be used as the length of the shutter, in frames.


Absolute Time Double Parameters
-------------------------------

Double parameters with their
:c:macro:`kOfxParamPropDoubleType` property set
to :c:macro:`kOfxParamDoubleTypeAbsoluteTime` are interpretted as an absolute
time from the begining of the effect. The host can represent these as
frames, seconds, milliseconds, millenia or whatever it feels is
appropriate. However, a plugin sees such values in 'frames' from the
beginning of a clip. Applicable only to 1D double parameters. It is an
error to set this on any other type of double parameter.

For example a plugin that stabalises all the images in a clip to a
specific frame would have a *reference frame* parameter and declare that
as an absolute time parameter and use its value to fetch a frame to
stablise against.

Spatial Parameters
------------------

Parameters that can represent a size or position are essential. To that
end there are several values of the
:c:macro:`kOfxParamPropDoubleType` that say it
should be interpretted as a size or position, in either one or two
dimensions.

The original OFX API only specified
:ref:`normalised <ParameterPropertiesDoubleTypesNormalised>` parameters,
this proved to be somewhat more of a problem than expected. With the 1.2
version of the API,
:ref:`spatial <ParameterPropertiesDoubleTypesStrictlySpatial>` parameters
were introduced. Ideally these should be used and the normalised
parameter types should be deprecated.

Plugins can check :c:macro:`kOfxPropAPIVersion` to see if
these new parameter types are supported, in hosts with version 1.2 or
greater they will be.

See the section on :ref:`coordinate systems <CoordinateSystems>` to
understand some of the terms being discussed.

.. _ParameterPropertiesDoubleTypesStrictlySpatial:

Spatial Double Parameters
~~~~~~~~~~~~~~~~~~~~~~~~~

These parameter types represent a size or position in one or two
dimensions in :ref:`Canonical Coordinate <CanonicalCoordinates>`. The host
and plug-in get and set values in this coordinate system. Scaling to
:ref:`Pixel Coordinate <PixelCoordinates>` is the reponsibility of the
effect.

The default value of a spatial parameter can be set in either a
normalised coordinate system or the canonical coordinate system. This is
controlled by the
:c:macro:`kOfxParamPropDefaultCoordinateSystem`
on the parameter descriptor with one of the following value:

.. doxygendefine:: kOfxParamCoordinatesCanonical

.. doxygendefine:: kOfxParamCoordinatesNormalised

Parameters can choose to be spatial in several ways...

-  :c:macro:`kOfxParamDoubleTypeX`
    size in the X dimension, in canonical coords (1D double only),
-  :c:macro:`kOfxParamDoubleTypeXAbsolute`
    positing in the X axis, in canonical coords (1D double only)
-  :c:macro:`kOfxParamDoubleTypeY`
    size in the Y dimension, in canonical coords (1D double only),
-  :c:macro:`kOfxParamDoubleTypeYAbsolute`
    positing in the Y axis, in canonical coords (1D double only)
-  :c:macro:`kOfxParamDoubleTypeXY`
    2D size, in canonical coords (2D double only),
-  :c:macro:`kOfxParamDoubleTypeXYAbsolute`
    2D position, in canonical coords. (2D double only).

.. _ParameterPropertiesDoubleTypesNormalised:

Spatial Normalised Double Parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Ideally, normalised parameters should be deprecated and no longer used
if :ref:`spatial <ParameterPropertiesDoubleTypesSpatial>` parameters are
available.

There are several values of the
:c:macro:`kOfxParamPropDoubleType` that say it
should be interpretted as a size or position. These are expressed and
proportional to the current project's size. This will allow the
parameter to scale cleanly with project size changes and to be
represented to the user in an appropriate range.

For example, the sensible X range of a visual effect plugin is the
project's width, say 768 pixels for a PAL D1 definition video project.
The user sees the parameter as 0..768, the effect sees it as 0..1. So if
the plug-in wanted to set the default value of an effect to be the
centre of the image, it would flag a 2D parameter as normalised and set
the defaults to be 0.5. The user would see this in the centre of the
image, no matter the resolution of the project in question. The plugin
would retrieve the parameter as 0..1 and scale it up to the project size
to size to use.

Parameters can choose to be normalised in several ways...

-  :c:macro:`kOfxParamDoubleTypeNormalisedX`
    normalised size wrt to the project's X dimension (1D only),
-  :c:macro:`kOfxParamDoubleTypeNormalisedXAbsolute`
    normalised absolute position on the X axis (1D only)
-  :c:macro:`kOfxParamDoubleTypeNormalisedY`
    normalised size wrt to the project's Y dimension(1D only),
-  :c:macro:`kOfxParamDoubleTypeNormalisedYAbsolute`
    normalised absolute position on the Y axis (1D only)
-  :c:macro:`kOfxParamDoubleTypeNormalisedXY`
    normalised to the project's X and Y size (2D only),
-  :c:macro:`kOfxParamDoubleTypeNormalisedXYAbsolute`
    normalised to the projects X and Y size, and is an absolute
   position on the image plane.

See the section on :ref:`coordinate systems <CoordinateSystems>` on how to
scale between normalised, cannonical and pixel coordinates.

.. ParameterPropertiesDoubleTypesDefaultsAndAll:

Double Parameters Defaults, Increments, Mins and Maxs
-----------------------------------------------------

In all cases double parameters' defaults, minimums and maximums are
specified in the same space as the parameter, as is the increment in all
cases but normalised parameters.

Normalised parameters specify thier increments in cannonical
coordinates, rather than in normalised coordinates. So an increment of
'1' means 1 pixel, not '1 project width', otherwise sliders would be a
bit wild.

.. ParametersParametric:

Parametric Parameters
---------------------

.. ParametersParametricIntro:

Introduction
^^^^^^^^^^^^

Parametric params are new for 1.2 and are optinally supported by host
applications. They are specified via the :c:macro:`kOfxParamTypeParametric`
identifier passed into
:cpp:func:`OfxParameterSuiteV1::paramDefine`

These parameters are somewhat more complex than normal parameters and
require their own set of functions to manage and manipulate them. The
new :cpp:class:`OfxParametricParameterSuiteV1`
is there to do that.

All the defines and suite definitions for parameteric parameters are
defined in the file `ofxParametricParam.h <https://github.com/ofxa/openfx/blob/master/include/ofxParametricParam.h>`_

Parametric parameters are in effect *functions* a plug-in can ask a host
to arbitrarily evaluate for some value *x*. A classic use case would be
for constructing look-up tables, a plug-in would ask the host to
evaluate one at multiple values from 0 to 1 and use that to fill an
array.

A host would probably represent this to a user as a cubic curve in a
standard curve editor interface, or possibly through scripting. The user
would then use this to define the 'shape' of the parameter.

The evaluation of such params is not the same as animation, they are
returning values based on some arbitrary argument orthogonal to time, so
to evaluate such a param, you need to pass a parametric position and
time.

Often, you would want such a parametric parameter to be
multi-dimensional, for example, a colour look-up table might want three
values, one for red, green and blue. Rather than declare three separate
parametric parameters, so a parametric parameter can be
multi-dimensional.

Due to the nature of the underlying data, you *cannot* call certain
functions in the ordinary parameter suite when manipulating a parametric
parameter. All functions in the standard parameter suite are valid when
called on a parametric parameter, with the exception of the
following....

-  :cpp:func:`OfxParameterSuiteV1::paramGetValue`
-  :cpp:func:`OfxParameterSuiteV1::paramGetValueAtTime`
-  :cpp:func:`OfxParameterSuiteV1::paramGetDerivative`
-  :cpp:func:`OfxParameterSuiteV1::paramGetIntegral`
-  :cpp:func:`OfxParameterSuiteV1::paramSetValue`
-  :cpp:func:`OfxParameterSuiteV1::paramSetValueAtTime`

Defining Parametric Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Parametric parameters are defined using the standard parameter suite
function
:cpp:func:`OfxParameterSuiteV1::paramDefine`.
The descriptor returned by this call have several non standard
parameter properties available. These are

-  :c:macro:`kOfxParamPropParametricDimension`
    the dimension of the parametric parameter,
-  :c:macro:`kOfxParamPropParametricUIColour`
    the colour of the curves of a parametric parameter in any user
   interface
-  :c:macro:`kOfxParamPropParametricInteractBackground`
    a pointer to an interact entry point, which will be used to draw a
   background under any user interface,
-  :c:macro:`kOfxParamPropParametricRange`
    the min and max value that the parameter will be evaluated over.

Animating Parametric Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Animation is an optional host feature for parametric parameters. Hosts
flag whether they support this feature by setting the host descriptor
property
:c:macro:`kOfxParamHostPropSupportsParametricAnimation`.

Getting and Setting Values on a Parametric Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Seeing as we need to pass in the parametric position and dimenstion to
evaluate, parametric parameters need a new evaluation mechanism. They do
this with the
:cpp:func:`OfxParametricParameterSuiteV1::parametricParamGetValue` function.
This function returns the value of the parameter at the given time, for
the given dimension, adt the given parametric position,.

Parametric parameters are effectively interfaces to some sort of host
based curve library. To get/set/delete points in the curve that
represents a parameter, the new suite has several functions available to
manipulate control points of the underlying curve.

To set the default value of a parametric parameter to anything but the
identity, you use the control point setting functions in the new suite
to set up a curve on the *descriptor* returned by
:cpp:func:`OfxParameterSuiteV1::paramDefine`.
Any instances later created, will have that curve as a default.

Example
^^^^^^^

This simple example defines a colour lookup table, defines a default,
and show how to evaluate the curve

    ::

        // describe our parameter in 
        static OfxStatus
        describeInContext( OfxImageEffectHandle  effect,  OfxPropertySetHandle inArgs)
        {
          ....
          // define it
          OfxPropertySetHandle props;
          gParamHost->paramDefine(paramSet, kOfxParamTypeParametric, "lookupTable", & props);

          // set standard names and labeles
          gPropHost->propSetString(props, kOfxParamPropHint, 0, "Colour lookup table");
          gPropHost->propSetString(props, kOfxParamPropScriptName, 0, "lookupTable");
          gPropHost->propSetString(props, kOfxPropLabel, 0, "Lookup Table");

          // define it as three dimensional
          gPropHost->propSetInt(props, kOfxParamPropParametricDimension, 0, 3);

          // label our dimensions are r/g/b
          gPropHost->propSetString(props, kOfxParamPropDimensionLabel, 0, "red");
          gPropHost->propSetString(props, kOfxParamPropDimensionLabel, 1, "green");
          gPropHost->propSetString(props, kOfxParamPropDimensionLabel, 2, "blue");

          // set the UI colour for each dimension
          for(int component = 0; component < 3; ++component) {
             gPropHost->propSetDouble(props, kOfxParamPropParametricUIColour, component * 3 + 0, component % 3 == 0 ? 1 : 0);
             gPropHost->propSetDouble(props, kOfxParamPropParametricUIColour, component * 3 + 1, component % 3 == 1 ? 1 : 0);
             gPropHost->propSetDouble(props, kOfxParamPropParametricUIColour, component * 3 + 2, component % 3 == 2 ? 1 : 0);
          }

          // set the min/max parametric range to 0..1
          gPropHost->propSetDouble(props, kOfxParamPropParametricRange, 0, 0.0);
          gPropHost->propSetDouble(props, kOfxParamPropParametricRange, 1, 1.0);
         
          // set a default curve, this example sets an invert 
          OfxParamHandle descriptor;
          gParamHost->paramGetHandle(paramSet, "lookupTable", &descriptor, NULL);
          for(int component = 0; component < 3; ++component) {
            // add a control point at 0, value is 1
            gParametricParamHost->parametricParamAddControlPoint(descriptor,
                                                                  component, // curve to set 
                                                                  0.0,   // time, ignored in this case, as we are not adding a ket
                                                                  0.0,   // parametric position, zero
                                                                  1.0,   // value to be, 1
                                                                  false);   // don't add a key
            // add a control point at 1, value is 0
            gParametricParamHost->parametricParamAddControlPoint(descriptor, component, 0.0, 1.0, 0.0, false);
          }
         
          ...
        }

        void render8Bits(double currentFrame, otherStuff...)
        {
           ...

           // make three luts from our curves   
           unsigned char lut[3][256];

          OfxParamHandle param;
          gParamHost->paramGetHandle(paramSet, "lookupTable", &param, NULL);
          for(int component = 0; component < 3; ++component) {
            for(int position = 0; position < 256; ++position) {
              // position to evaluate the param at
              float parametricPos = float(position)/255.0f;
               
              // evaluate the parametric param
              float value;
              gParametricParamHost->parametricParamGetValue(param, component, currentFrame, parametricPos, &value);
              value = value * 255;
              value = clamp(value, 0, 255);

              // set that in the lut
              lut[dimension][position] = (unsigned char)value;
            }
          }
          ...
        }

.. _SettingParams:

Setting Parameters
------------------

Plugins are free to set parameters in limited set of circumstances,
typically relating to user interaction. You can only set parameters in
the following actions passed to the plug-in's :ref:`main entry <mainEntry>`
function...

-  :c:macro:`kOfxActionCreateInstance`
-  :c:macro:`kOfxActionBeginInstanceChanged`
-  :c:macro:`kOfxActionInstanceChanged`
-  :c:macro:`kOfxActionEndInstanceChanged`
-  :c:macro:`kOfxActionSyncPrivateData`

Plugins can also set parameter values during the following actions
passed to any of its interacts main entry function:

-  :c:macro:`kOfxInteractActionPenDown`
-  :c:macro:`kOfxInteractActionPenMotion`
-  :c:macro:`kOfxInteractActionPenUp`
-  :c:macro:`kOfxInteractActionKeyDown`
-  :c:macro:`kOfxInteractActionKeyRepeat`
-  :c:macro:`kOfxInteractActionKeyUp`
-  :c:macro:`kOfxInteractActionLoseFocus`
