OpenFX

https://openfx.readthedocs.io/en/main
Admin
OpenFX is an open standard for image processing plug-ins, providing a framework for developing and...
Tokens:425,586
Snippets:2,690
Trust Score:8.3
Update:6 days ago
Show doc for...
Tokens:
Raw
### Proposed example plugins list

Source: https://openfx.readthedocs.io/en/main/Guide/index.html

Text block listing proposed example plugins to be added to the guides, including OpenGL Overlay, Temporal Difference, Transition, Custom Parameter, 3x3 2D Filter, Analysis Plugin, and Basic OpenGL Example.

```text
This is a brief description of examples which could
do with being added to the Guides.

The following examples should be added to the guide.

OpenGL Overlay Example
======================
A trivial example along the lines of the circle drawing example.

This will illustrate...
    - openGL overlays


Temporal Difference Example
===========================
Compute the absolute difference between images at two different times.

This will illustrate...
    - fetching images at separate times
    - the get frames needed action

Transition Example
===========================
A simple straight frame blend transition

This will illustrate...
   - the transition context


Custom Parameter
================
Something like the circle drawing plugin so that it has no double parameters, but only a single custom parameter, controlled via the overlay UI.

This will illustrate...
    - using custom parameters.


3x3 2D Filter
=============
Does a variety of simple 2D filtering operations using a 3x3 window.

This will illustrate...
   - the get region of interest action


Analysis Plugin
===============
The plugin will find the minimum and maximum value of a given frame in response to a push button, and store the values
into two parameters. During renders it will rescale pixel values so that 'min' is 0 and 'max' is the whitepoint.

This will illustrate...
    - writing to parameters in response to a button press outside of render.


Basic OpenGL Example
==============
Behaviour to be determined.

This will illustrate the basics of rendering in OpenGL
   
Last Edit 11/11/14

```

--------------------------------

### Create instance action: get property set

Source: https://openfx.readthedocs.io/en/main/_sources/Guide/ofxExample4_Saturation.rst.txt

Starts the create instance action by retrieving the effect's property set. The source notes this action has slight changes to handle the mask input.

```c++
      ////////////////////////////////////////////////////////////////////////////////
      /// instance construction
      OfxStatus CreateInstanceAction( OfxImageEffectHandle instance)
      {
        OfxPropertySetHandle effectProps;
        gImageEffectSuite->getPropertySet(instance, &effectProps);
```

--------------------------------

### Set string property kOfxPropLabel in basics.cpp

Source: https://openfx.readthedocs.io/en/main/Guide/ofxExample1_Basics.html

Uses the effect suite to get the property set on the effect, then sets the string property kOfxPropLabel to "OFX Basics Example". The third argument 0 is an index for multidimensional properties. The pointer returned by fetching a string property is only valid until the next OFX suite call or action end, so it must be copied if used beyond that scope.

```cpp
OfxPropertySetHandle effectProps;
gImageEffectSuite->getPropertySet(effect, &effectProps);

gPropertySuite->propSetString(effectProps, kOfxPropLabel, 0, "OFX Basics Example");

```

--------------------------------

### Directory tree and build instructions

Source: https://openfx.readthedocs.io/en/main/Guide/index.html

Text block describing the directory tree and build commands for plugins and documentation. Use cmake to generate builds and run scripts/build-cmake.sh; documentation is built with Documentation/build.sh.

```text
This directory tree contains a set of plugins and corresponding
guides which take you through the basics of the OFX
Image Effects Plugin API.

There are two sub-directories...
   - Code - which contains the example plugins source files,
   - Doc  - has a guide to each plugin.

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
BUILDING THE PLUGINS

The plugins and support libs are set up to use cmake to generate and run builds.
See the top-level README.md in the repo, and use `scripts/build-cmake.sh`.

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
BUILDING THE DOCUMENTATION

See the file Documentation/README, and use `Documentation/build.sh`.
The docs are also auto-generated on commit to the main branch on github.

```

--------------------------------

### StrChoice Parameter Setup

Source: https://openfx.readthedocs.io/en/main/_sources/Reference/ofxParameter.rst.txt

Example of setting up a StrChoice parameter with options and enum values using the property host.

```APIDOC
## StrChoice Parameter Setup

### Description
Sets the option labels and enum values for a StrChoice parameter.

### Method
N/A (Property setting)

### Endpoint
N/A

### Parameters
- **paramHandle** (OfxParamHandle) - The handle to the StrChoice parameter.
- **optionIndex** (int) - Index of the option (0-based).
- **optionString** (const char*) - The display label for the option.
- **enumString** (const char*) - The enum value stored in the project.

### Request Example
```cpp
gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, 0, "1st Choice");
gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, 1, "2nd Choice");
gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, 2, "3rd Choice");
// enums: string values to be returned as param value, and stored by the host in the project
gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceEnum, 0, "choice-1");
gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceEnum, 1, "choice-2");
gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceEnum, 2, "choice-3");
```

### Response
No response. The property is set on the host.

### Notes
- The default value must be one of the specified enums, otherwise behavior is undefined.
- If no default is set, the host uses the first option (index 0).
- Option and Enum arrays must be the same length.
- Gaps in choices after describe action are an error.
- If a plugin removes enums and a project uses a removed enum, behavior is undefined; host should use default value.
- Check host property `kOfxParamHostPropSupportsStrChoice` for availability.
- StrChoice parameters can be reordered using `kOfxParamPropChoiceOrder`.
- Available since OFX 1.5.
```

--------------------------------

### progressStart

Source: https://openfx.readthedocs.io/en/main/Reference/api/struct/structOfxProgressSuiteV1.html

Initiates a progress bar display. Call this to initiate the display of a progress bar.

```APIDOC
## progressStart

### Description
Initiates a progress bar display. Call this to initiate the display of a progress bar.

### Function Signature
`OfxStatus (*progressStart)(void *effectInstance, const char *label)`

### Parameters
- `effectInstance` (void*) - Required - The instance of the plugin this progress bar is associated with. It cannot be NULL.
- `label` (const char*) - Required - A text label to display in any message portion of the progress object's user interface. A UTF8 string.

### Preconditions
- There is no currently ongoing progress display for this instance.

### Return Values
- `kOfxStatOK` - The handle is now valid for use.
- `kOfxStatFailed` - The progress object failed for some reason.
- `kOfxStatErrBadHandle` - `effectInstance` was invalid.
```

--------------------------------

### CreateInstanceAction: cache clip and param handles in instance data

Source: https://openfx.readthedocs.io/en/main/Guide/ofxExample3_Gain.html

Implements the create instance action. Allocates a MyInstanceData struct, stores it in the instance property set, and fetches handles to the 'Source' and 'Output' clips and to the GAIN_PARAM_NAME and APPLY_TO_ALPHA_PARAM_NAME parameters.

```cpp
////////////////////////////////////////////////////////////////////////////////
/// instance construction
OfxStatus CreateInstanceAction( OfxImageEffectHandle instance)
{
  OfxPropertySetHandle effectProps;
  gImageEffectSuite->getPropertySet(instance, &effectProps);

  // To avoid continual lookup, put our handles into our instance
  // data, those handles are guaranteed to be valid for the duration
  // of the instance.
  MyInstanceData *myData = new MyInstanceData;

  // Set my private instance data
  gPropertySuite->propSetPointer(effectProps, kOfxPropInstanceData, 0, (void *) myData);

  // Cache the source and output clip handles
  gImageEffectSuite->clipGetHandle(instance, "Source", &myData->sourceClip, 0);
  gImageEffectSuite->clipGetHandle(instance, "Output", &myData->outputClip, 0);

  // Cache away the param handles
  OfxParamSetHandle paramSet;
  gImageEffectSuite->getParamSet(instance, &paramSet);
  gParameterSuite->paramGetHandle(paramSet,
                                  GAIN_PARAM_NAME,
                                  &myData->gainParam,
                                  0);
  gParameterSuite->paramGetHandle(paramSet,
                                  APPLY_TO_ALPHA_PARAM_NAME,
                                  &myData->applyToAlphaParam,
                                  0);

  return kOfxStatOK;
}

```

--------------------------------

### kOfxActionLoad

Source: https://openfx.readthedocs.io/en/main/Reference/api/file/ofxCore_8h.html

This action is the first action passed to a plug-in after the binary containing the plug-in has been loaded. It allows a plug-in to create any global data structures it may need and is also when the plug-in should fetch suites from the host.

```APIDOC
## kOfxActionLoad

### Description
This action is the first action passed to a plug-in after the binary containing the plug-in has been loaded. It is there to allow a plug-in to create any global data structures it may need and is also when the plug-in should fetch suites from the host. The handle, inArgs and outArgs arguments to the mainEntry are redundant and should be set to NULL.

### Preconditions
- The plugin’s OfxPlugin::setHost function has been called

### Postconditions
- This action will not be called again while the binary containing the plug-in remains loaded.

### Returns
- kOfxStatOK, the action was trapped and all was well
- kOfxStatReplyDefault, the action was ignored
- kOfxStatFailed, the load action failed, no further actions will be passed to the plug-in. Interpret if possible kOfxStatFailed as plug-in indicating it does not want to load. Do not create an entry in the host’s UI for plug-in then. Plug-in also has the option to return 0 for OfxGetNumberOfPlugins or kOfxStatFailed if host supports OfxSetHost in which case kOfxActionLoad will never be called.
- kOfxStatErrFatal, fatal error in the plug-in.
```

--------------------------------

### propGetDimension

Source: https://openfx.readthedocs.io/en/main/Reference/api/file/ofxProperty_8h.html

Gets the dimension of the property.

```APIDOC
## propGetDimension

### Description
Gets the dimension of the property.

### Function Signature
`OfxStatus (*propGetDimension)(OfxPropertySetHandle properties, const char *property, int *count)`

### Parameters
- **properties** (OfxPropertySetHandle) - Required - Handle of the thing holding the property.
- **property** (const char*) - Required - String labelling the property.
- **count** (int*) - Required - Pointer to an integer where the value is returned.

### Return Values
- kOfxStatOK
- kOfxStatErrBadHandle
- kOfxStatErrUnknown

```

--------------------------------

### getTimeBounds

Source: https://openfx.readthedocs.io/en/main/Reference/suites/ofxTimeLineSuiteReference.html

Gets the current bounds on a timeline.

```APIDOC
## getTimeBounds

### Description
Get the current bounds on a timeline.

### Method
Function pointer

### Signature
`OfxStatus (*getTimeBounds)(void *instance, double *firstTime, double *lastTime)`

### Parameters
- **instance** (void *) - The instance of the effect, cast to a void *.
- **firstTime** (double *) - The first time on the timeline, in the temporal coordinate system of the effect.
- **lastTime** (double *) - The last time on the timeline, in the temporal coordinate system of the effect.

### Return
- `kOfxStatOK` - The time enquiry was successful.
- `kOfxStatFailed` - The enquiry failed for some host specific reason.
- `kOfxStatErrBadHandle` - The effect handle was invalid.
```

--------------------------------

### progressStart

Source: https://openfx.readthedocs.io/en/main/Reference/suites/ofxProgressSuiteReference.html

Initiates a progress bar display for a plugin instance. It takes an effect instance and a label, and returns a status indicating success or failure.

```APIDOC
## progressStart

### Description
Initiates a progress bar display. Call this to initiate the display of a progress bar.

### Function Pointer
`OfxStatus (*progressStart)(void *effectInstance, const char *label)`

### Parameters
- **effectInstance** (void*) - Required - The instance of the plugin this progress bar is associated with. It cannot be NULL.
- **label** (const char*) - Required - A text label to display in any message portion of the progress object's user interface. A UTF8 string.

### Preconditions
- There is no currently ongoing progress display for this instance.

### Return Values
- **kOfxStatOK** - The handle is now valid for use.
- **kOfxStatFailed** - The progress object failed for some reason.
- **kOfxStatErrBadHandle** - effectInstance was invalid.
```

--------------------------------

### DescribeInContextAction: Get Param Set and Define Gain Parameter

Source: https://openfx.readthedocs.io/en/main/_sources/Guide/ofxExample3_Gain.rst.txt

In the DescribeInContextAction, the code gets the parameter set handle from the effect descriptor and defines a double parameter named 'gain'. The parameter name uniquely identifies it within the API.

```c++
      OfxStatus
      DescribeInContextAction(OfxImageEffectHandle descriptor,
                              OfxPropertySetHandle inArgs)
      {
        ...
        BIG SNIP OF EXACTLY THE SAME CODE IN THE LAST EXAMPLE
        ...

        // first get the handle to the parameter set
        OfxParamSetHandle paramSet;
        gImageEffectSuite->getParamSet(descriptor, &paramSet);

        // properties on our parameter
        OfxPropertySetHandle paramProps;

        // now define a 'gain' parameter and set its properties
        gParameterSuite->paramDefine(paramSet,
                                     kOfxParamTypeDouble,
                                     GAIN_PARAM_NAME,
                                     &paramProps);
```

--------------------------------

### OfxProgressSuiteV2

Source: https://openfx.readthedocs.io/en/main/Reference/api/file/ofxProgress_8h.html

Suite V2 adds an ID that can be looked up for internationalisation and so on. When a new version is introduced, because plug-ins need to support old versions, and plug-in's new releases are not necessary in synch with hosts (or users don't immediately update), best practice is to support the 2 suite versions. That is, the plugin should check if V2 exists; if not then check if V1 exists. This way a graceful transition is guaranteed. So plugin should fetchSuite passing 2, (OfxProgressSuiteV2*) fetchSuite(mHost->mHost->host, kOfxProgressSuite,2); and if no success pass (OfxProgressSuiteV1*) fetchSuite(mHost->mHost->host, kOfxProgressSuite,1);

```APIDOC
## OfxProgressSuiteV2

### Description
Suite V2 adds an ID that can be looked up for internationalisation and so on. When a new version is introduced, because plug-ins need to support old versions, and plug-in's new releases are not necessary in synch with hosts (or users don't immediately update), best practice is to support the 2 suite versions. That is, the plugin should check if V2 exists; if not then check if V1 exists. This way a graceful transition is guaranteed. So plugin should fetchSuite passing 2, (OfxProgressSuiteV2*) fetchSuite(mHost->mHost->host, kOfxProgressSuite,2); and if no success pass (OfxProgressSuiteV1*) fetchSuite(mHost->mHost->host, kOfxProgressSuite,1);

### Usage
To obtain the suite, use the host's fetchSuite function with the appropriate version number. For V2, pass 2 as the version. If that fails, fall back to V1 by passing 1.
```

--------------------------------

### OfxParameterSuiteV1::paramGetValue

Source: https://openfx.readthedocs.io/en/main/Reference/ofxParameter.html

Gets the current value of a parameter.

```APIDOC
## OfxParameterSuiteV1::paramGetValue

### Description
Gets the current value of a parameter during rendering and interactions.

### Method
paramGetValue

### Parameters
- **param** (OfxParamHandle) - Required - Handle to the parameter.
- **...** (varies) - Required - Pointers to receive the parameter values.

### Returns
OfxStatus - Status code indicating success or failure.
```

--------------------------------

### OFX main entry point handling actions

Source: https://openfx.readthedocs.io/en/main/_sources/Guide/ofxExample1_Basics.rst.txt

The plugin's main entry point receives an action string, a handle, and input/output argument property sets. It casts the handle to an OfxImageEffectHandle and returns kOfxStatReplyDefault to let the host handle unhandled actions.

```c++
      OfxStatus MainEntryPoint(const char *action,
                               const void *handle,
                               OfxPropertySetHandle inArgs,
                               OfxPropertySetHandle outArgs)
      {
        // cast to appropriate type
        OfxImageEffectHandle effect = (OfxImageEffectHandle) handle;

        OfxStatus returnStatus = kOfxStatReplyDefault;
```

--------------------------------

### Set up OpenGL viewport for render-to-texture

Source: https://openfx.readthedocs.io/en/main/Reference/DoxygenIndex.html

Shows how to set up the OpenGL viewport rooted at the bottom left of the output texture, using the render window dimensions. The host creates a default viewport sized to the render window, and the effect must leave output in the provided output image texture buffer.

```cpp
  // set up the OpenGL context for the render to texture
  ...

  // figure the size of the render window
  int dx = renderWindow.x2 - renderWindow.x1;
  int dy = renderWindow.y2 - renderWindow.y2;

  // setup the output viewport
  glViewport(0, 0, dx, dy);

```

--------------------------------

### propGetIntN

Source: https://openfx.readthedocs.io/en/main/Reference/api/file/ofxProperty_8h.html

Gets multiple values of an int property.

```APIDOC
## propGetIntN

### Description
Get multiple values of an int property.

### Function Signature
`OfxStatus (*propGetIntN)(OfxPropertySetHandle properties, const char *property, int count, int *value)`

### Parameters
- **properties** (OfxPropertySetHandle) - Required - Handle of the thing holding the property.
- **property** (const char*) - Required - String labelling the property.
- **count** (int) - Required - Number of values to get (indices 0..count-1).
- **value** (int*) - Required - Pointer to an array where the property values will be returned.

### Return Values
- kOfxStatOK
- kOfxStatErrBadHandle
- kOfxStatErrUnknown
- kOfxStatErrBadIndex

```

--------------------------------

### OfxActionCreateInstance

Source: https://openfx.readthedocs.io/en/main/_sources/Reference/ofxPropertySetsGenerated.rst.txt

Action called to create an instance. No input or output arguments.

```APIDOC
## OfxActionCreateInstance

### Description
Action called to create an instance.

### Input Arguments
None.

### Output Arguments
None.
```

--------------------------------

### propGetDoubleN

Source: https://openfx.readthedocs.io/en/main/Reference/api/file/ofxProperty_8h.html

Gets multiple values of a double property.

```APIDOC
## propGetDoubleN

### Description
Get multiple values of a double property.

### Function Signature
`OfxStatus (*propGetDoubleN)(OfxPropertySetHandle properties, const char *property, int count, double *value)`

### Parameters
- **properties** (OfxPropertySetHandle) - Required - Handle of the thing holding the property.
- **property** (const char*) - Required - String labelling the property.
- **count** (int) - Required - Number of values to get (indices 0..count-1).
- **value** (double*) - Required - Pointer to an array where the property values will be returned.

### Return Values
- kOfxStatOK
- kOfxStatErrBadHandle
- kOfxStatErrUnknown
- kOfxStatErrBadIndex

```

--------------------------------

### propGetStringN

Source: https://openfx.readthedocs.io/en/main/Reference/api/file/ofxProperty_8h.html

Gets multiple values of a string property.

```APIDOC
## propGetStringN

### Description
Get multiple values of a string property.

### Function Signature
`OfxStatus (*propGetStringN)(OfxPropertySetHandle properties, const char *property, int count, char **value)`

### Parameters
- **properties** (OfxPropertySetHandle) - Required - Handle of the thing holding the property.
- **property** (const char*) - Required - String labelling the property.
- **count** (int) - Required - Number of values to get (indices 0..count-1).
- **value** (char**) - Required - Pointer to an array where the property values will be returned.

### Return Values
- kOfxStatOK
- kOfxStatErrBadHandle
- kOfxStatErrUnknown
- kOfxStatErrBadIndex

```

--------------------------------

### OfxProgressSuiteV1::progressStart

Source: https://openfx.readthedocs.io/en/main/Reference/DoxygenIndex.html

Initiates a progress bar display for a plugin instance. Call this to start showing a progress bar with a label.

```APIDOC
## progressStart

### Description
Initiates a progress bar display. Call this to initiate the display of a progress bar.

### Function Signature
`OfxStatus (*progressStart)(void *effectInstance, const char *label)`

### Parameters
- **effectInstance** (void*) - Required - The instance of the plugin this progress bar is associated with. It cannot be NULL.
- **label** (const char*) - Required - A text label to display in any message portion of the progress object's user interface. A UTF8 string.

### Preconditions
- There is no currently ongoing progress display for this instance.

### Return Values
- **kOfxStatOK** - The handle is now valid for use.
- **kOfxStatFailed** - The progress object failed for some reason.
- **kOfxStatErrBadHandle** - effectInstance was invalid.
```

--------------------------------

### Main entry point action dispatch for OpenFX plugin

Source: https://openfx.readthedocs.io/en/main/_sources/Guide/ofxExample1_Basics.rst.txt

This snippet shows the main entry point of an OpenFX image effect plugin, which dispatches seven actions: kOfxActionLoad, kOfxActionUnload, kOfxActionDescribe, kOfxImageEffectActionDescribeInContext, kOfxActionCreateInstance, kOfxActionDestroyInstance, and kOfxImageEffectActionIsIdentity. It returns the status from the corresponding action handler. Only four actions are strictly required for an image effect plugin, but this example traps more for illustration.

```c++
if(strcmp(action, kOfxActionLoad) == 0) {
          returnStatus = LoadAction();
        }
        else if(strcmp(action, kOfxActionUnload) == 0) {
          returnStatus = UnloadAction();
        }
        else if(strcmp(action, kOfxActionDescribe) == 0) {
          returnStatus = DescribeAction(effect);
        }
        else if(strcmp(action, kOfxImageEffectActionDescribeInContext) == 0) {
          returnStatus = DescribeInContextAction(effect, inArgs);
        }
        else if(strcmp(action, kOfxActionCreateInstance) == 0) {
          returnStatus = CreateInstanceAction(effect);
        }
        else if(strcmp(action, kOfxActionDestroyInstance) == 0) {
          returnStatus = DestroyInstanceAction(effect);
        }
        else if(strcmp(action, kOfxImageEffectActionIsIdentity) == 0) {
          returnStatus = IsIdentityAction(effect, inArgs, outArgs);
        }

        return returnStatus;
```
Tokens:
Raw