ofxParametricParam.h

Go to the documentation of this file.

#ifndef _ofxParametricParam_h_
#define _ofxParametricParam_h_

/*
Software License :

Copyright (c) 2009, The Open Effects Association Ltd. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright notice,
      this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright notice,
      this list of conditions and the following disclaimer in the documentation
      and/or other materials provided with the distribution.
    * Neither the name The Open Effects Association Ltd, nor the names of its 
      contributors may be used to endorse or promote products derived from this
      software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/

/** @file ofxParametricParam.h
 
This header file defines the optional OFX extension to define and manipulate parametric
parameters.

*/

#include "ofxParam.h"

#ifdef __cplusplus
extern "C" {
#endif

/** @brief string value to the ::kOfxPropType property for all parameters */
#define kOfxParametricParameterSuite "OfxParametricParameterSuite"


/**
   \defgroup ParamTypeDefines Parameter Type definitions 

These strings are used to identify the type of the parameter when it is defined, they are also on the ::kOfxParamPropType in any parameter instance.
*/
/*@{*/

/** @brief String to identify a param as a single valued integer */
#define kOfxParamTypeParametric "OfxParamTypeParametric"

/*@}*/

/**
   \addtogroup PropertiesAll
*/
/*@{*/
/**
   \defgroup ParamPropDefines Parameter Property Definitions 

These are the list of properties used by the parameters suite.
*/
/*@{*/

/** @brief The dimension of a parametric param

    - Type - int X 1
    - Property Set - parametric param descriptor (read/write) and instance (read only)
    - default - 1
    - Value Values - greater than 0

This indicates the dimension of the parametric param.
*/
#define kOfxParamPropParametricDimension "OfxParamPropParametricDimension"

/** @brief The colour of parametric param curve interface in any UI.

    - Type - double X N
    - Property Set - parametric param descriptor (read/write) and instance (read only)
    - default - unset, 
    - Value Values - three values for each dimension (see ::kOfxParamPropParametricDimension)
      being interpretted as R, G and B of the colour for each curve drawn in the UI.

This sets the colour of a parametric param curve drawn a host user interface. A colour triple
is needed for each dimension of the oparametric param. 

If not set, the host should generally draw these in white.
*/
#define kOfxParamPropParametricUIColour "OfxParamPropParametricUIColour"

/** @brief Interact entry point to draw the background of a parametric parameter.
 
    - Type - pointer X 1
    - Property Set - plug-in parametric parameter descriptor (read/write) and instance (read only),
    - Default - NULL, which implies the host should draw its default background.
 
Defines a pointer to an interact which will be used to draw the background of a parametric 
parameter's user interface.  None of the pen or keyboard actions can ever be called on the interact.
 
The openGL transform will be set so that it is an orthographic transform that maps directly to the
'parametric' space, so that 'x' represents the parametric position and 'y' represents the evaluated
value.
*/
#define kOfxParamPropParametricInteractBackground "OfxParamPropParametricInteractBackground"

/** @brief Property on the host to indicate support for parametric parameter animation.
 
    - Type - int X 1
    - Property Set - host descriptor (read only)
    - Valid Values 
      - 0 indicating the host does not support animation of parmetric params,
      - 1 indicating the host does support animation of parmetric params,
*/
#define kOfxParamHostPropSupportsParametricAnimation "OfxParamHostPropSupportsParametricAnimation"

/** @brief Property to indicate the min and max range of the parametric input value.
 
    - Type - double X 2
    - Property Set - parameter descriptor (read/write only), and instance (read only)
    - Default Value - (0, 1)
    - Valid Values - any pair of numbers so that  the first is less than the second.

This controls the min and max values that the parameter will be evaluated at.
*/
#define kOfxParamPropParametricRange "OfxParamPropParametricRange"

/*@}*/
/*@}*/


/** @brief The OFX suite used to define and manipulate 'parametric' parameters.

This is an optional suite.

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, it would be better to have one such parameter 
with multiple values in it.

The major complication with these parameters is how to allow a plug-in to set values, and 
defaults. The default default value of a parametric curve is to be an identity lookup. If
a plugin wishes to set a different default value for a curve, it can use the suite to set
key/value pairs on the \em descriptor of the param. When a new instance is made, it will
have these curve values as a default.
*/
typedef struct OfxParametricParameterSuiteV1 {
  
  /** @brief Evaluates a parametric parameter
 
      \arg param                 handle to the parametric parameter
      \arg curveIndex            which dimension to evaluate
      \arg time                  the time to evaluate to the parametric param at
      \arg parametricPosition    the position to evaluate the parametric param at
      \arg returnValue           pointer to a double where a value is returned
 
      @returns
        - ::kOfxStatOK            - all was fine 
        - ::kOfxStatErrBadHandle  - if the paramter handle was invalid
        - ::kOfxStatErrBadIndex   - the curve index was invalid
  */
  OfxStatus (*parametricParamGetValue)(OfxParamHandle param,
                                       int   curveIndex,
                                       OfxTime time,
                                       double parametricPosition,
                                       double *returnValue);


  /** @brief Returns the number of control points in the parametric param.

      \arg param                 handle to the parametric parameter
      \arg curveIndex            which dimension to check
      \arg time                  the time to check
      \arg returnValue           pointer to an integer where the value is returned.
      
      @returns
        - ::kOfxStatOK            - all was fine 
        - ::kOfxStatErrBadHandle  - if the paramter handle was invalid
        - ::kOfxStatErrBadIndex   - the curve index was invalid
   */
  OfxStatus (*parametricParamGetNControlPoints)(OfxParamHandle param,
                                                int   curveIndex,
                                                double time,
                                                int *returnValue);
 
  /** @brief Returns the key/value pair of the nth control point.

      \arg param                 handle to the parametric parameter
      \arg curveIndex            which dimension to check
      \arg time                  the time to check
      \arg nthCtl                the nth control point to get the value of
      \arg key                   pointer to a double where the key will be returned
      \arg value                 pointer to a double where the value will be returned 
            
      @returns
        - ::kOfxStatOK            - all was fine 
        - ::kOfxStatErrBadHandle  - if the paramter handle was invalid
        - ::kOfxStatErrUnknown    - if the type is unknown
   */
  OfxStatus (*parametricParamGetNthControlPoint)(OfxParamHandle param,
                                                 int    curveIndex,
                                                 double time,
                                                 int    nthCtl,
                                                 double *key,
                                                 double *value);
 
  /** @brief Modifies an existing control point on a curve

      \arg param                 handle to the parametric parameter
      \arg curveIndex            which dimension to set
      \arg time                  the time to set the value at 
      \arg nthCtl                the control point to modify
      \arg key                   key of the control point
      \arg value                 value of the control point
      \arg addAnimationKey       if the param is an animatable, setting this to true will 
                                 force an animation keyframe to be set as well as a curve key,
                                 otherwise if false, a key will only be added if the curve is already
                                 animating.

      @returns
        - ::kOfxStatOK            - all was fine 
        - ::kOfxStatErrBadHandle  - if the paramter handle was invalid
        - ::kOfxStatErrUnknown    - if the type is unknown

      This modifies an existing control point. Note that by changing key, the order of the
      control point may be modified (as you may move it before or after anther point). So be
      careful when iterating over a curves control points and you change a key.
   */
  OfxStatus (*parametricParamSetNthControlPoint)(OfxParamHandle param,
                                                 int   curveIndex,
                                                 double time,
                                                 int   nthCtl,
                                                 double key,
                                                 double value,
                                                 bool addAnimationKey);

  /** @brief Adds a control point to the curve.

      \arg param                 handle to the parametric parameter
      \arg curveIndex            which dimension to set
      \arg time                  the time to set the value at
      \arg key                   key of the control point
      \arg value                 value of the control point
      \arg addAnimationKey       if the param is an animatable, setting this to true will 
                                 force an animation keyframe to be set as well as a curve key,
                                 otherwise if false, a key will only be added if the curve is already
                                 animating.

      @returns
        - ::kOfxStatOK            - all was fine 
        - ::kOfxStatErrBadHandle  - if the paramter handle was invalid
        - ::kOfxStatErrUnknown    - if the type is unknown

      This will add a new control point to the given dimension of a parametric parameter. If a key exists
      sufficiently close to 'key', then it will be set to the indicated control point.
   */
  OfxStatus (*parametricParamAddControlPoint)(OfxParamHandle param,
                                              int   curveIndex,
                                              double time,
                                              double key,
                                              double value,
                                              bool addAnimationKey);
  
  /** @brief Deletes the nth control point from a parametric param.

      \arg param                 handle to the parametric parameter
      \arg curveIndex            which dimension to delete
      \arg nthCtl                the control point to delete
   */
  OfxStatus (*parametricParamDeleteControlPoint)(OfxParamHandle param,
                                                 int   curveIndex,
                                                 int   nthCtl);

  /** @brief Delete all curve control points on the given param.

      \arg param                 handle to the parametric parameter
      \arg curveIndex            which dimension to clear
   */
  OfxStatus (*parametricParamDeleteAllControlPoints)(OfxParamHandle param,
                                                     int   curveIndex);
 } OfxParametricParameterSuiteV1;

#ifdef __cplusplus
}
#endif




#endif