OpenFX plugin programming guide (Advanced issues)

OpenFX plugin tricks

Context-dependent choice menus

Some plugins carry kOfxParamTypeChoice parameters whose options depend on the plugin "environment":

• clip connections
• environment variables
• content of configuration files
• system environment (e.g. a list of fonts)

The problem is that, if the menu options are built from the environment at plugin creation or when connection clips, the numerical value stored in the kOfxParamTypeChoice is meaningless and may point to a completely different option value.

A general rule is to not use these parameters to store the actual option, but to use a secret "backup" parameter (usually a kOfxParamTypeString) to store the actual value.

That way,

1. The choice parameter descriptor should have kOfxParamPropEvaluateOnChange=0 and kOfxParamPropPersistant=0.
2. The backup string parameter descriptor may have kOfxParamPropSecret=1
3. The selected option in the choice parameter should be set in kOfxActionCreateInstance and whenever the choice menu is rebuilt or updated (in kOfxActionInstanceChanged). Note that some OFX hosts (e.g. Nuke) do not support rebuilding kOfxParamTypeChoice parameters after instance creation (propReset has no effect on the GUI).
4. The string parameter should be set in kOfxActionInstanceChanged whenever the choice parameter is changed, and only if the new value is different from the old one (to avoid infinite recursion on bad hosts)
5. The value of the string parameter should be used in the render action, rather than the choice menu, because it holds the "real" value.

Portability issues

Compatibility with hosts that do not support recent OpenFX specs

Some hosts had their OpenFX layer implemented when OFX 1.2, 1.3 or 1.4 were not yet available, and were not updated since. To avoid crashing the plugin on these hosts, when using a property that was introduced after OFX 1.0, be careful that it may not exist, and propGet* or propSet* may return kOfxStatErrUnknown. The Plugins/Support library usually takes care of these if you use functions from this library, but be careful if you fetch or set these properties manually (e.g. kOfxPropVersion on a plugin instance).

Secret and disabled parameters

On Nuke (and maybe other OFX hosts), when a parameter descriptor is secret or disabled, the parameter instance can never be shown or enabled. For parameters that may be shown but should be secret by default, the kOfxParamPropSecret property should be set in kOfxActionCreateInstance (i.e. in the plugin constructor if using the Support library). Same holds for parameters that should be disabled by default but ma be re-enabled.

Host-specific features

DaVinci Resolve Lite

OFX API version 1.3
hostName=DaVinciResolveLite
hostLabel=DaVinci Resolve Lite
hostVersion=11.1.4 (11.1.4)
hostIsBackground=0
supportsOverlays=1
supportsMultiResolution=0
supportsTiles=0
temporalClipAccess=1
supportedComponents=OfxImageComponentRGBA,OfxImageComponentAlpha
supportedContexts=OfxImageEffectContextFilter,OfxImageEffectContextGeneral,OfxImageEffectContextTransition,OfxImageEffectContextGenerator
supportedPixelDepths=OfxBitDepthFloat,OfxBitDepthShort,OfxBitDepthByte
supportsMultipleClipDepths=0
supportsMultipleClipPARs=0
supportsSetableFrameRate=0
supportsSetableFielding=0
supportsStringAnimation=0
supportsCustomInteract=0
supportsChoiceAnimation=0
supportsBooleanAnimation=0
supportsCustomAnimation=0
supportsParametricAnimation=0
canTransform=0
maxParameters=-1
pageRowCount=0
pageColumnCount=0
isNatron=0
supportsDynamicChoices=0
supportsCascadingChoices=0
supportsChannelSelector=0
suites=OfxImageEffectSuite,OfxPropertySuite,OfxParameterSuite,OfxMemorySuite,OfxMessageSuite,OfxMessageSuiteV2,OfxProgressSuite,OfxTimeLineSuite

• doesn't support symbolic links in /Library/OFX/Plugins (at least on OS X)
• in Generators, even if the source clip is defined, it can not be fetched by the plug-in
• all defined clips will appear connected but give black and transparent (NULL) images. This is a problem for Mask clips, so a "Mask" boolean param must be added for this host
• kOfxImagePropField property is always kOfxImageFieldNone on OFX images
• The display range has to be defined for all Double params (kOfxParamTypeDouble, kOfxParamTypeDouble2D, kOfxParamTypeDouble3D), or a default range of (-1,1) is used, and values cannot lie outside of this range, whatever value range was set!
• kOfxParamPropDefaultCoordinateSystem=kOfxParamCoordinatesNormalised is not supported (although API version 1.3 is claimed by the host)
• kOfxParamTypeInteger2D kOfxParamTypeInteger3D are not supported (crash when opening the parameters page), at least in Generators

Nuke

OFX API version 1.2
hostName=uk.co.thefoundry.nuke
hostLabel=nuke
hostVersion=9.0.6 (9.0v6)
hostIsBackground=0
supportsOverlays=1
supportsMultiResolution=1
supportsTiles=1
temporalClipAccess=1
supportedComponents=OfxImageComponentRGBA,OfxImageComponentAlpha,uk.co.thefoundry.OfxImageComponentMotionVectors,uk.co.thefoundry.OfxImageComponentStereoDisparity
supportedContexts=OfxImageEffectContextFilter,OfxImageEffectContextGeneral
supportedPixelDepths=OfxBitDepthFloat
supportsMultipleClipDepths=0
supportsMultipleClipPARs=0
supportsSetableFrameRate=0
supportsSetableFielding=0
supportsStringAnimation=0
supportsCustomInteract=1
supportsChoiceAnimation=1
supportsBooleanAnimation=1
supportsCustomAnimation=0
supportsParametricAnimation=0
canTransform=1
maxParameters=-1
pageRowCount=0
pageColumnCount=0
isNatron=0
supportsDynamicChoices=0
supportsCascadingChoices=0
supportsChannelSelector=0
suites=OfxImageEffectSuite,OfxPropertySuite,OfxParameterSuite,OfxMemorySuite,OfxMessageSuite,OfxMessageSuiteV2,OfxProgressSuite,OfxTimeLineSuite,OfxParametricParameterSuite,NukeOfxCameraSuite,uk.co.thefoundry.FnOfxImageEffectPlaneSuiteV1,uk.co.thefoundry.FnOfxImageEffectPlaneSuiteV2

• ChoiceParam items can only be set during description and cannot be changed afterwards
• Params that are described as secret can never be "revealed", they are doomed to remain secret (fix: set them as secret at the end of effect instance creation)
• kOfxParamTypeParametric is not supported in Nuke 8 and 9 (they crash the host), but is supported in Nuke 6 and 7

Natron

OFX API version 1.4
hostName=fr.inria.Natron
hostLabel=Natron
hostVersion=2.0.0 (2.0.0)
hostIsBackground=0
supportsOverlays=1
supportsMultiResolution=1
supportsTiles=1
temporalClipAccess=1
supportedComponents=OfxImageComponentRGBA,OfxImageComponentAlpha,OfxImageComponentRGB,uk.co.thefoundry.OfxImageComponentMotionVectors,uk.co.thefoundry.OfxImageComponentStereoDisparity
supportedContexts=OfxImageEffectContextGenerator,OfxImageEffectContextFilter,OfxImageEffectContextGeneral,OfxImageEffectContextTransition
supportedPixelDepths=OfxBitDepthFloat,OfxBitDepthShort,OfxBitDepthByte
supportsMultipleClipDepths=1
supportsMultipleClipPARs=0
supportsSetableFrameRate=0
supportsSetableFielding=0
supportsStringAnimation=1
supportsCustomInteract=1
supportsChoiceAnimation=1
supportsBooleanAnimation=1
supportsCustomAnimation=1
supportsParametricAnimation=0
canTransform=1
maxParameters=-1
pageRowCount=0
pageColumnCount=0
isNatron=1
supportsDynamicChoices=1
supportsCascadingChoices=1
supportsChannelSelector=1
suites=OfxImageEffectSuite,OfxPropertySuite,OfxParameterSuite,OfxMemorySuite,OfxMessageSuite,OfxMessageSuiteV2,OfxProgressSuite,OfxTimeLineSuite,OfxParametricParameterSuite,uk.co.thefoundry.FnOfxImageEffectPlaneSuiteV1,uk.co.thefoundry.FnOfxImageEffectPlaneSuiteV2,OfxVegasStereoscopicImageEffectSuite

• may give a fake hostName for plugins that don't officially support Natron, but sets an extra host property kNatronOfxHostIsNatron
• the isidentity action may point to a frame on the output clip (the spec only allows pointing to frames on the input clips), which is useful for generators, readers, and plugins that are not kOfxImageEffectFrameVarying at every frame.

SGO MambaFX

OFX API version 1.3
hostName=Mistika
hostLabel=2.4.10 Beta
versionMajor=6
versionMinor=5
versionMicro=0
versionLabel=2.4.10 Beta
hostIsBackground=false
supportsOverlays=true
supportsMultiResolution=true
supportsTiles=false
temporalClipAccess=true
supportsMultipleClipDepths=true
supportsMultipleClipPARs=false
supportsSetableFrameRate=false
supportsSetableFielding=false
sequentialRender=0
supportsStringAnimation=false
supportsCustomInteract=true
supportsChoiceAnimation=true
supportsBooleanAnimation=true
supportsCustomAnimation=false
supportsParametricParameter=false
supportsParametricAnimation=false
supportsRenderQualityDraft=false
nativeOrigin=eNativeOriginBottomLeft 
maxParameters=0
maxPages=0
pageRowCount=0
pageColumnCount=0
supportedComponents=ePixelComponentRGBA, ePixelComponentAlpha
supportedContexts=eContextGenerator, eContextFilter, eContextTransition, eContextGeneral, eContextRetimer
supportedPixelDepths=eBitDepthUByte, eBitDepthUShort
supportsProgressSuite=true
supportsTimeLineSuite=false
supportsMessageSuiteV2=true