The Describe Action

// the plug-in's description routine
static OfxStatus
describe(OfxImageEffectHandle effect)
  // get the property handle for the plugin
  OfxPropertySetHandle effectProps;
  gEffectSuite->getPropertySet(effect, &effectProps);

  // say we cannot support multiple pixel depths and let the clip preferences action deal with it all.
  gPropertySuite->propSetInt(effectProps, kOfxImageEffectPropSupportsMultipleClipDepths, 0, 0);
  // set the bit depths the plug-in can handle
  gPropertySuite->propSetString(effectProps, kOfxImageEffectPropSupportedPixelDepths, 0, kOfxBitDepthByte);

  // set plug-in label and the group it belongs to
  gPropertySuite->propSetString(effectProps, kOfxPropLabel, 0, "OFX Invert Example");
  gPropertySuite->propSetString(effectProps, kOfxImageEffectPluginPropGrouping, 0, "OFX Example");

  // define the contexts we can be used in
  gPropertySuite->propSetString(effectProps, kOfxImageEffectPropSupportedContexts, 0, kOfxImageEffectContextFilter);
  return kOfxStatOK;

The purpose of the describe action is to tell the host the overall behaviour of the plug-in. The OfxImageEffectHandle passed to the describe action is a descriptor as opposed to an instance . A descriptor is a handle that is used to tell the host how a plug-in should look, whilst an instance is an actual running copy of a plug-in. Descriptors are passed to only two actions, the describe action, and the describe in context action. Most other actions that are passed an instance handle.

The first thing this function does is to fetch the handle holding the properties used to describe the plug-in. Note how it uses the gEffectSuite pointer to do this.

The next thing the plug-in does is set the integer property kOfxImageEffectPropSupportsMultipleClipDepths to be false using the property suite. This tells the host application that the plug-in can only support a single pixel depth at a time, otherwise the host might attempt to have an 8 bit input and a 16 bit output.

Note how the property setting functions take four arguments. The first is the set of properties to be modified, the second is the name (again a string) of the property in that set they wish to change, the third is the index of the property (as properties can be multi-dimensional) and the last is the value they wish to set.

The plug-in goes on to set properties that describe it as supporting only images of 8 bits per component, the user visible name of the effect, the grouping the effect should be placed in on any user interface and finally the context it can be used under.

An image effect context describes the semantics of how a plug-in should be used. In this case we are saying the plug-in is a filter, which means it has to have one input clip called "Source" and one output clip called "Output". Other contexts include transitions, where an image effect has two inputs and a single output and is require to go from one to the other, a general context for tree based compositing systems and several more. A plug-in can say that it works in more than one context, which brings us on to the next function.