Chapter 5. Image Effect Contexts

How an image effect is used by an end user affects how it should interact with a host application. For example an effect that is to be used as a transition between two clips works differently to an effect that is a simple filter. One must have two inputs and know how much to mix between the two input clips, the other has fewer constraints on it. Within OFX we have standardised several different uses and have called them contexts .

More specifically, a context mandates certain behaviours from an effect when it is described or instantiated in that context. The major issue is the number of input clips it takes, and how it can interact with those input clips.

All OFX contexts have a single output clip and zero or more input clips. The current contexts defined in OFX are..

  • generator
    • no compulsory input clips
    • used by a host to create imagery from scratch, eg: a noise generator,
  • filter
    • a single compulsory input clip
    • a traditional 'filter effect' that transforms a single input in some way, eg: a simple blur
  • transition
    • two compulsory input clips and a compulsory 'Transition' double parameter
    • used to perform transitions between clips, typically in editing applications, eg: a cross dissolve,
  • paint effect
    • two compulsory input clips, one image to paint onto, the other a mask to control where the effect happens,
    • used by hosts to use an effect under a paint brush,
  • retimer
    • a single compulsory input clip, and a compulsory 'SourceTime' double parameter,
    • used by a host to change the playback speed of a clip,
  • general effect
    • an arbitrary number of inputs,
    • generally used in a 'tree' compositing environment,
    • a catch all context.

A host or plug-in need not support all contexts. For example a host that does not have any paint facility within it should not need to support the paint context, or a simple blur effect need not support the retimer context.

An effect may say that it can be used in more than one context, for example a blur effect that acts as a filter, with a single input to blur, and a general effect, with an input to blur and an optional input to act as a mask to attenuate the blur. In such cases a host should choose the most appropriate context for the way that host's architecture. With our blur example, a tree based compositing host should simply ignore the filter context and always use it in the general context.

Plugins and hosts inform each other what contexts they work in via the multidimensional kOfxImageEffectPropSupportedContexts property. It must be set to at least one of the following values...

  • kOfxImageEffectContextGenerator
  • kOfxImageEffectContextFilter
  • kOfxImageEffectContextTransition
  • kOfxImageEffectContextPaint
  • kOfxImageEffectContextGeneral
  • kOfxImageEffectContextRetimer

A host indicates which contexts it supports by setting the kOfxImageEffectPropSupportedContexts property in the global host descriptor. A plugin indicates which contexts it supports by setting this on the effect descriptor passed to the kOfxActionDescribe action.

Because a plugin can work in different ways, it needs the ability to describe itself to the host in different ways. This is the purpose of the kOfxImageEffectActionDescribeInContext action. This action is called once for each context that the effect supports, and the effect gets to describe the input clips and parameters appropriate to that context. This means that an effect can have different sets of parameters and clips in different contexts, though it will most likely have a core set of parameters that it uses in all contexts. From our blur example, both the filter and general contexts would have a 'blur radius' parameter, but the general context might have an 'invert matte' parameter.

During the kOfxImageEffectActionDescribeInContext action, an effect must describe all clips and parameters that it intends to use. This includes the mandated clips and parameters for that context.

A plugin instance is created in a specific contex which will not changed over the lifetime of that instance. The context can be retrieved from the instance via the kOfxImageEffectPropContext property on the instance handle.

The Generator Context

A generator context is for cases where a plugin can create images without any input clips, eg: a colour bar generator.

In this context, a plugin has the following mandated clips,

  • an output clip named 'Output'

Any input clips that are specified must be optional.

A host is responsible for setting the initial preferences of the output clip, it must do this in a manner that is transparent to the plugin. So the pixel depths, components, fielding, frame rate and pixel aspect ratio are under the control of the host. How it arrives at these is a matter for the host, but as a plugin specifies what components it can produce on output, as well as the pixel depths it supports, the host must choose one of these.

Generators still have Regions of Definition. This should generally be,

  • based on the project size eg: an effect that renders a 3D sky simulation,
  • based on parameter settings eg: an effect that renders a circle in an arbitrary location,
  • infinite, which implies the effect can generate output anywhere on the image plane.

The pixel preferences action is constrained in this context by the following,

  • a plugin cannot change the component type of the 'Output' clip,