Chapter 12. Image Effect Clip Preferences

The kOfxImageEffectActionGetClipPreferences action is passed to an effect to allow a plugin to specify how it wishes to deal with it's input clips and to set properties in it's output clip. This is especially important when there are multiple inputs of which my have differing properties, eg; pixel depth.

More specifically, there are six properties that can be set during the clip preferences action, some on the input clip, some on the output clip, some on both. These are...

  • the depth of a clip's pixels, input or output clip,
  • the components of a clip's pixels, input or output clip,
  • the pixel aspect ratio of a clip, input or output clip,
  • the frame rate of the output clip,
  • the fielding of the output clip,
  • the premultiplication state of the output clip,
  • whether the output clip varys from frame to frame, even if no paramerters or input images change over time,
  • whether the output clip can be sampled at sub-frame times and produce different images.

The behaviour specified by OFX means that a host may need to cast images from their native data format into one suitable for the plugin. It is better that the host do any of this pixel shuffling because,

  • the behaviour is orthogonal for all plugins on that host,
  • the code is not replicated in all plugins,
  • the host can optimise the pixel shuffling in one pass with any other data grooming it may need to do.

A plugin gets to assert its clip preferences in several situations. Firstly whenever a clip is attached to a plugin, secondly whenever one of the parameters in the plugin property kOfxImageEffectPropClipPreferencesSlaveParam has its value changed. The clip preferences action is never called until all non optional clips have been attached to the plugin.


  • these properties cannot animate over the duration of an effect,
  • that the ability to set input and output clip preferences is restricted by the context of an effect,
  • optional input clips do not have any context specific restrictions on plugin set preferences.

Frame Varying Effects

Some plugins can generate differing output frames at different times, even if no parameters animate or no input images change. The kOfxImageEffectFrameVarying property set in the clip preferences action is used to flag this.

A counter example is a solid colour generator. If it has no animating parameters, the image generated at frame 0 will be the same as the image generated at any other frame. Intellegent hosts can render a single frame and cache that for use at all other times.

On the other hand, a plugin that generates random noise at each frame, and seeds its random number generator with the render time, will create different images at different times. The host cannot render a single frame and cache that for use at subsequent times.

To differentiate between these two cases the kOfxImageEffectFrameVarying is used. If set to 1, it indicates that the effect will need to be rendered at each frame, even if no input images or parameters are varying. If set to 0, then a single frame can be rendered and used for all times if no input images or parameters vary. The default value is 0.