OpenFX (OFX) Documentation

OpenFX version 1.4 introduces several new capabilities for plugin developers and host implementations:

• Dialog Suite: The OfxDialogSuiteV1 allows plugins to request that the host display a modal dialog.
• Progress Suite Updates: OfxProgressSuiteV2 is available, providing an internationalizable version of the progress reporting mechanism.
• Draft Render Quality: Support for draft render quality via the kOfxImageEffectPropRenderQualityDraft property.
• Native Origin: The kOfxImageEffectHostPropNativeOrigin property allows hosts to communicate the native origin of the image.
• CPU Rendering Improvements: The half-float format tag is now available for CPU rendering, extending support beyond just OpenGL.
• Clarified Semantics: The specification clarifies that OpenGL processing and tiled rendering can be enabled or disabled within Instance Changed events. It also clarifies the semantics for dialogs and the progress suite.

Plugins and hosts communicate using a property mechanism. A property is a named object within a property set (similar to a dictionary). You access these using the property suite defined in ofxProperty.h.

Fundamental Types:

• int
• double
• char * (strings)
• void *

Multidimensional Properties: Properties can be multidimensional (e.g., a 2D integer for pen position). You can access individual elements via an index or set all values at once using functions like OfxPropertySuiteV1::propSetIntN.

Important Memory Note: When fetching a string property, the returned pointer is only guaranteed to be valid until the next call to an OFX suite function or until the current action ends. If you need to use the string outside this scope, you must copy it.

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

// Setting a string property using kOfxPropLabel
gPropertySuite->propSetString(effectProps, kOfxPropLabel, 0, "OFX Basics Example");

In certain OFX contexts, the host application communicates state to the plug-in using specific 'pseudo-parameters'. These are not intended to be exposed on the plug-in's user interface (UI) for manual user adjustment; instead, the host manages them implicitly or via its own UI (like a timeline or a curve).

Transition Context

Requires a double parameter named Transition. The host uses this to indicate the progress of a transition between two clips. The host calculates this value based on the current frame's position relative to the transition duration.

Retimer Context

Requires a double parameter named SourceTime. The host uses this to communicate the mapping of the current frame to the source media time. The host may derive this value from a timeline stretch or a 'speed' parameter.

// Conceptual logic for how a host might calculate the Transition parameter:
Transition = (currentFrame - startOfTransition) / lengthOfTransition;

Plugins can signal to the host how they generate images over time using two specific properties during the kOfxImageEffectActionGetClipPreferences action:

Frame Varying Effects

Use kOfxImageEffectFrameVarying to indicate if an effect produces different images even when parameters and inputs are static (e.g., a random noise generator).

• Set to 1: The effect must be rendered at every frame. The host cannot cache a single frame for all time.
• Set to 0 (Default): If inputs and parameters don't change, the host can render one frame and reuse it.

Continuously Sampled Effects

Use kOfxImageClipPropContinuousSamples to indicate if an effect can generate images at non-frame-time boundaries (sub-frame rendering).

• Set to true: The plugin supports sampling at arbitrary times (e.g., a fractal cloud generator with a speed parameter).
• Default: false.
• Note: All retimer effects are implicitly continuously sampled.