The Generic Describe Action
Prev   Chapter 13. Actions Passed to An Image Effect   Next

The Generic Describe Action 

	#include "ofxCore.h"
	#define kOfxActionDescribe "OfxActionDescribe"
Arguments

  • handle handle to the plug-in descriptor, cast to an OfxImageEffectHandle
  • inArgs is redundant and is set to NULL,
  • outArgs is redundant and is set to NULL.

Description

The kOfxActionDescribe is the second action passed to a plug-in. It is where a plugin defines how it behaves and the resources it needs to function.

Note that the handle passed in acts as a descriptor for, rather than an instance of the plugin. The handle is global and unique. The plug-in is at liberty to cache the handle away for future reference until the plug-in is unloaded.

Most importantly, the effect must set what image effect contexts it is capable of working in.

This action must be trapped, it is not optional.

Preconditions

kOfxActionLoad has been called

Postconditions

  • kOfxActionDescribe will not be called again, unless it fails and returns one of the error codes where the host is allowed to attempt the action again
  • the handle argument, being the global plug-in description handle, is a valid handle from the end of a sucessful describe action until the end of the kOfxActionUnload action (ie: the plug-in can cache it away without worrying about it changing between actions).
  • kOfxImageEffectActionDescribeInContext will be called once for each context that the host and plug-in mutually support.

Return Values

  • kOfxStatOK, the action was trapped and all was well
  • kOfxStatErrMissingHostFeature, in which the plugin will be unloaded and ignored, plugin may post message
  • kOfxStatErrMemory, in which case describe may be called again after a memory purge
  • kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message
  • kOfxStatErrFatal

Prev   Up   Next
The Generic Unload Action  Home  The Generic Create Instance Action