 <chapter id="ImageEffectActions">
  <title>Actions Passed to An Image Effect</title>
  <para>
    Actions passed to an OFX Image Effect's plug-in main entry point are from two categories...
    <itemizedlist>
      <listitem>actions that could potentially be issued to any kind of plug in, not just image effects, known as generic actions, found in <filename>ofxCore.h</filename></listitem>
      <listitem>actions that are only applicable purely to image effects, found in <filename>ofxImageEffect.h</filename></listitem>
    </itemizedlist>
  </para>
  <para>
    For generic actions, the <code>handle</code> passed to to main entry point will depend on the API being impemented, for all generic actions passed to an OFX Image Effect plug-in, it will nearly alway be an <code>OfxImageEffectHandle</code>.
  </para>
  <para>
    Because interacts are a special case, they are dealt with in a separate chapter, this chapter will deal with actions issued to an image effect plug-ins main entry point.
  </para>
  
  <section id="kOfxActionLoad"><title>The Generic Load Action</title>
    <blockquote><programlisting>
	#include "ofxCore.h"
	#define  kOfxActionLoad "OfxActionLoad" </programlisting></blockquote>
    &arguments;
    <para>
      The <code>handle</code>, <code>inArgs</code> and <code>outArgs</code> arguments to the main entry are redundant and should be set to NULL.
    </para>
    
    &description;
    <para><code>kOfxActionLoad</code> is the first action passed to a plug-in after the binary containing the plug-in has been loaded. It is there to allow a plug-in to create any global data structures it may need and is also when the plug-in should fetch suites from the host.</para>
    
    &preconditions;
    <para>
      The plugin's OfxPlugin::setHost function has been called
    </para>
    
    &postconditions;
    <para>
      This action will not be called again while the binary containing the plug-in remains loaded.
    </para>
    
    &returnValues;
    <itemizedlist>
      <listitem>kOfxStatOK, the action was trapped and all was well,</listitem>
      <listitem>kOfxStatReplyDefault, the action was ignored,</listitem>
      <listitem>kOfxStatFailed, the load action failed, no further actions will be passed to the plug-in,</listitem>
      <listitem>kOfxStatErrFatal, fatal error in the plug-in.</listitem>
    </itemizedlist>
  </section>
  
  <section id="kOfxActionUnload"><title >The Generic Unload Action</title>
    <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxActionUnload "OfxActionUnload" </programlisting></blockquote>
    &description;
    <para>kOfxActionUnload is the last action passed to the plug-in before the binary containing the plug-in is unloaded. It is there to allow a plug-in to destroy any global data structures it may have created.</para>
    
    &arguments;
    <para>
      The <code>handle</code>, <code>inArgs</code> and <code>outArgs</code> arguments to the main entry are redundant and should be set to NULL.</para>
    
    &preconditions;
    <para>
      <itemizedlist>
	<listitem>the kOfxActionLoad action has been called</listitem>
	<listitem>all instances of a plugin have been destroyed</listitem>
      </itemizedlist>
    </para>
    
    &postconditions;
    <para>
      No other actions will be called.
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem>kOfxStatOK, the action was trapped all was well</listitem>
	<listitem>kOfxStatReplyDefault, the action was ignored</listitem>
	<listitem>kOfxStatErrFatal, in which case we the program will be forced to quit</listitem>
      </itemizedlist>
    </para>
    
  </section>
  
  <section id="kOfxActionDescribe"><title >The Generic Describe Action</title>
    <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxActionDescribe "OfxActionDescribe" </programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the plug-in descriptor, cast to an <code>OfxImageEffectHandle</code></listitem>
	<listitem><code>inArgs</code> is redundant and is set to NULL,</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>      
    &description;
    <para>
      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.
      </para>
    
    <para>
      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.
    </para>
    
    <para>
      Most importantly, the effect must set what image effect contexts it is capable of working in.
    </para>
    
    <para>
      This action <emphasis>must</emphasis> be trapped, it is not optional.
    </para>
    
    &preconditions;
    <para>
      kOfxActionLoad has been called
    </para>
    
    &postconditions;
    <para>
      <itemizedlist>
	<listitem>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</listitem>
	<listitem>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).</listitem>
	<listitem><link linkend="kOfxImageEffectActionDescribeInContext"><code>kOfxImageEffectActionDescribeInContext</code></link> will be called once for each context that the host and plug-in mutually support.</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem>kOfxStatOK, the action was trapped and all was well</listitem>
	<listitem>kOfxStatErrMissingHostFeature, in which the plugin will be unloaded and ignored, plugin may post message</listitem>
	<listitem>kOfxStatErrMemory, in which case describe may be called again after a memory purge</listitem>
	<listitem>kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message</listitem>
	<listitem>kOfxStatErrFatal</listitem>
      </itemizedlist>
    </para>
    
  </section>
  
  <section id="kOfxActionCreateInstance"><title >The Generic Create Instance Action</title>
    <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxActionCreateInstance        "OfxActionCreateInstance" </programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the plug-in instance, cast to an <code>OfxImageEffectHandle</code> </listitem>
	<listitem><code>inArgs</code> is redundant and is set to NULL,</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    
    &description;
    <para>
      The kOfxActionCreateInstance is the first action passed to a plug-in's instance after its creation. It is there to allow a plugin to create
      any per-instance data structures it may need.
    </para>
    
    &preconditions;
    <para>
      <itemizedlist>
	<listitem>kOfxActionDescribe has been called</listitem>
	<listitem>the instance is fully constructed, with all objects requested in the describe actions (eg, parameters and clips) have been constructed and have had their initial values set. This means that if the values are being loaded from an old setup, that load should have taken place before the create instance action is called.</listitem>
      </itemizedlist>
    </para>
    
    &postconditions;
    <para>
      <itemizedlist>
	<listitem>the instance pointer will be valid until the <link linkend="kOfxActionDestroyInstance"><code>kOfxActionDestroyInstance</code></link> action is passed to the plug-in with the same instance handle</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem>kOfxStatOK, the action was trapped and all was well</listitem>
	<listitem>kOfxStatReplyDefault, the action was ignored, but all was well anyway</listitem>
	<listitem>kOfxStatErrFatal</listitem>
	<listitem>kOfxStatErrMemory, in which case this may be called again after a memory purge</listitem>
	<listitem>kOfxStatFailed, something went wrong, but no error code appropriate, the plugin should to post a message if possible and the host should destroy the instanace handle and not attempt to proceed further</listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="kOfxActionDestroyInstance"><title >The Generic Destroy Instance Action</title>
    <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxActionDestroyInstance       "OfxActionDestroyInstance" </programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the plug-in instance, cast to an <code>OfxImageEffectHandle</code> </listitem>
	<listitem><code>inArgs</code> is redundant and is set to NULL,</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    
    &description;
    <para>
      This action is the last passed to a plug-in's instance before its destruction. It is there to allow a plugin to destroy
      any per-instance data structures it may have created.
    </para>
    
    &preconditions;
    <para>
      <itemizedlist>
	<listitem><code>kOfxActionCreateInstance</code> has been called on the handle,</listitem>
	<listitem>the instance has not had any of its members destroyed yet, </listitem>
      </itemizedlist>
    </para>
    
    &postconditions;
    <para>
      <itemizedlist>	
	<listitem>the instance pointer is no longer valid and any operation on it will be undefined</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      To some extent, what is returned is moot, a bit like throwing an exception in a C++ destructor, so the host should continue destruction of the
      instance regardless. However...
      <itemizedlist>	
	<listitem>kOfxStatOK, the action was trapped and all was well,</listitem>
	<listitem>OfxStatReplyDefault, the action was ignored as the effect had nothing to do, </listitem>
	<listitem>kOfxStatErrFatal,</listitem>
	<listitem>kOfxStatFailed, something went wrong, but no error code appropriate, the plugin should to post a message.</listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="kOfxActionBeginInstanceChanged"><title id="kOfxActionEndInstanceChanged">The Generic Begin/End Instance Changed Actions</title>
    <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxActionBeginInstanceChanged "OfxActionBeginInstanceChanged" 
	#define kOfxActionEndInstanceChanged "OfxActionEndInstanceChanged" </programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the plug-in instance, cast to an <code>OfxImageEffectHandle</code> </listitem>
	<listitem><code>inArgs</code> has the following properties...
	  <itemizedlist>
	    <listitem><link linkend="kOfxPropChangeReason">kOfxPropChangeReason</link> - what triggered the change, which will be one of...
	      <itemizedlist>
		<listitem>kOfxChangeUserEdited - the user or host changed the instance somehow and caused a change to something, this includes undo/redos, resets and loading values from files or presets,</listitem>
		<listitem>kOfxChangePluginEdited - the plugin itself has changed the value of the instance in some action</listitem>
		<listitem>kOfxChangeTime         - the time has changed and this has affected the value of the object because it varies over time</listitem>
	      </itemizedlist>
	    </listitem>
	  </itemizedlist>
	</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    
    &description;
    <para>
      <code>kOfxActionBeginInstanceChanged</code> and <code>kOfxActionEndInstanceChanged</code> are used to bracket all <code>kOfxActionInstanceChanged</code> actions, whether a single change or multiple changes.
      Some changes to a plugin instance can be grouped logically (eg: a 'reset all' button resetting all the instance's parameters), the begin/end instance changed actions allow a plugin to respond appropriately to a large set of changes.
      For example, a plugin that maintains a complex internal state can delay any changes to that state until all parameter changes have completed.
    </para>
    
    &preconditions;
    <para>
      For kOfxActionBeginInstanceChanged,
      <itemizedlist>
	<listitem>kOfxActionCreateInstance has been called on the instance handle.</listitem>
      </itemizedlist>
      For kOfxActionEndInstanceChanged,
      <itemizedlist>
	<listitem>kOfxActionBeginInstanceChanged has been called on the instance handle.</listitem>
	<listitem>kOfxActionCreateInstance has been called on the instance handle.</listitem>
      </itemizedlist>
    </para>
    
    &postconditions;
    <para>
      For kOfxActionBeginInstanceChanged,
      <itemizedlist>
	<listitem>kOfxActionInstanceChanged will be called at least once on the instance handle.</listitem>
	<listitem>kOfxActionEndInstanceChanged will be called on the instance handle.</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem>kOfxStatOK, the action was trapped and all was well</listitem>
	<listitem>kOfxStatReplyDefault, the action was ignored</listitem>
	<listitem>kOfxStatErrFatal, </listitem>
	<listitem>kOfxStatFailed, something went wrong, but no error code appropriate, the plugin should to post a message</listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="kOfxActionInstanceChanged"><title >The Generic Instance Changed Action</title>
    <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxActionInstanceChanged "OfxActionInstanceChanged" </programlisting></blockquote>
    
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the plug-in instance, cast to an <code>OfxImageEffectHandle</code> </listitem>
	<listitem><code>inArgs</code> has the following properties...
	  <itemizedlist>
	    <listitem><link linkend="kOfxPropType">kOfxPropType</link> - the type of the thing that changed which will be one of..
	      <itemizedlist>
		<listitem>kOfxTypeParameter - indicating a parameter's value has changed in some way</listitem>
		<listitem>kOfxTypeClip      - a clip to an image effect has changed in some way (for Image Effect Plugins only)</listitem>
	      </itemizedlist>
	    </listitem>
	    <listitem><link linkend="kOfxPropName">kOfxPropName</link> - the name of the thing that was changed in the instance</listitem>
	    <listitem><link linkend="kOfxPropChangeReason">kOfxPropChangeReason</link> - what triggered the change, which will be one of...
	      <itemizedlist>
		<listitem>kOfxChangeUserEdited - the user or host changed the instance somehow and caused a change to something, this includes undo/redos, resets and loading values from files or presets,</listitem>
		<listitem>kOfxChangePluginEdited - the plugin itself has changed the value of the instance in some action</listitem>
		<listitem>kOfxChangeTime         - the time has changed and this has affected the value of the object because it varies over time</listitem>
	      </itemizedlist>
	    </listitem>
	    <listitem><link linkend="kOfxPropTime">kOfxPropTime</link> - the effect time at which the chang occured (for Image Effect Plugins only)</listitem>
	    <listitem><link linkend="kOfxImageEffectPropRenderScale">kOfxImageEffectPropRenderScale</link> - the render scale currently being applied to any image fetched from a clip (for Image Effect Plugins only)</listitem>
	  </itemizedlist>
	</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    
    &description;
    <para>
      This action signals that something has changed in a plugin's instance, either by user action, the host or the plugin itself. All change actions are bracketed by a pair of kOfxActionBeginInstanceChanged and kOfxActionEndInstanceChanged actions. The <code>inArgs</code> property set is used to determine what was the thing inside the instance that was changed.
    </para>
    
    &preconditions;
    <para>
      <itemizedlist>
	<listitem>kOfxActionCreateInstance has been called on the instance handle,</listitem>
	<listitem>kOfxActionBeginInstanceChanged has been called on the instance handle.</listitem>
      </itemizedlist>
    </para>
    
    &postconditions;
    <para>
      <itemizedlist>
	<listitem>kOfxActionEndInstanceChanged will be called on the instance handle.</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem>kOfxStatOK, the action was trapped and all was well</listitem>
	<listitem>kOfxStatReplyDefault, the action was ignored</listitem>
	<listitem>kOfxStatErrFatal, </listitem>
	<listitem>kOfxStatFailed, something went wrong, but no error code appropriate, the plugin should to post a message</listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="kOfxActionPurgeCaches"><title >The Generic Purge Caches Action</title>
    <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxActionPurgeCaches                 "OfxActionPurgeCaches"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the plug-in instance, cast to an <code>OfxImageEffectHandle</code> </listitem>
	<listitem><code>inArgs</code> is redundant and is set to NULL,</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    
    &description;
    <para>
      The kOfxActionPurgeCaches is an action that may be passed to a plug-in instance from time to
      time in low memory situations. Instances recieving this action should destroy any data structures they may have and release the associated memory, they can later reconstruct this from the effect's parameter set and associated information.
    </para>
    <para>
      For Image Effects, it is generally a bad idea to call this after each render, but rather it should be called after <link linkend="kOfxImageEffectActionEndSequenceRender"><code>kOfxImageEffectActionEndSequenceRender</code></link>. Some effects, typically those flagged with the <link linkend="kOfxImageEffectInstancePropSequentialRender">kOfxImageEffectInstancePropSequentialRender</link> property, may need to cache information from previously rendered frames to function correctly, or have data structures that are expensive to reconstruct at each frame (eg: a particle system). Ideally, such effect should free such structures during the <code>kOfxImageEffectActionEndSequenceRender</code> action.
    </para>
    
    &preconditions;
    <para>
      <itemizedlist>
	<listitem>kOfxActionCreateInstance has been called on the instance handle,</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem>kOfxStatOK, the action was trapped and all was well</listitem>
	<listitem>kOfxStatReplyDefault, the action was ignored</listitem>
	<listitem>kOfxStatErrFatal, </listitem>
	<listitem>kOfxStatFailed, something went wrong, but no error code appropriate, the plugin should to post a message</listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="kOfxActionSyncPrivateData"><title >The Sync Private Data Action</title>
    <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxActionSyncPrivateData                 "OfxActionSyncPrivateData"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the plug-in instance, cast to an <code>OfxImageEffectHandle</code> </listitem>
	<listitem><code>inArgs</code> is redundant and is set to NULL,</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    
    &description;
    <para>
      This action is called when a plugin should synchronise any private data structures to its parameter set. This
      generally occurs when an effect is about to be saved or copied, but it could occur in other situations as well.
    </para>
    
    
    &preconditions;
    <para>
      <itemizedlist>
	<listitem>kOfxActionCreateInstance has been called on the instance handle,</listitem>
      </itemizedlist>
    </para>
    
    &postconditions;
    <para>
      <itemizedlist>
	<listitem>any private state data can be reconstructed from the parameter set,</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem>kOfxStatOK, the action was trapped and all was well</listitem>
	<listitem>kOfxStatReplyDefault, the action was ignored</listitem>
	<listitem>kOfxStatErrFatal, </listitem>
	<listitem>kOfxStatFailed, something went wrong, but no error code appropriate, the plugin should to post a message</listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="kOfxActionBeginInstanceEdit"><title >The Generic Begin Instance Edit Action</title>
    <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxActionBeginInstanceEdit "OfxActionBeginInstanceEdit"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the plug-in instance, cast to an <code>OfxImageEffectHandle</code> </listitem>
	<listitem><code>inArgs</code> is redundant and is set to NULL,</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    &description;
    <para>
      This is called when an instance is <emphasis>first</emphasis> actively edited by a user, ie: and interface is open and parameter values and input clips can be modified. It is there so that effects can create private user interface structures when necassary. Note that some hosts can have multiple editors open on the same effect instance simulateously.
    </para>	
    
    &preconditions;
    <para>
      <itemizedlist>
	<listitem>kOfxActionCreateInstance has been called on the instance handle,</listitem>
      </itemizedlist>
    </para>
    
    &postconditions;
    <para>
      <itemizedlist>
	<listitem>kOfxActionEndInstanceEdit will be called when the last editor is closed on the instance</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem>kOfxStatOK, the action was trapped and all was well</listitem>
	<listitem>kOfxStatReplyDefault, the action was ignored</listitem>
	<listitem>kOfxStatErrFatal, </listitem>
	<listitem>kOfxStatFailed, something went wrong, but no error code appropriate, the plugin should to post a message</listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="kOfxActionEndInstanceEdit"><title >The Generic End Instance Edit Action</title>
    <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxActionEndInstanceEdit "OfxActionEndInstanceEdit"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the plug-in instance, cast to an <code>OfxImageEffectHandle</code> </listitem>
	<listitem><code>inArgs</code> is redundant and is set to NULL,</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    &description;
    <para>
      This is called when the <emphasis>last</emphasis> user interface on an instance closed. It is there so that effects can destroy private user interface structures when necassary. Note that some hosts can have multiple editors open on the same effect instance simulateously, this will only be called when the last of those editors are closed.
    </para>	
    
    &preconditions;
    <para>
      <itemizedlist>
	<listitem>kOfxActionBeginInstanceEdit has been called on the instance handle,</listitem>
      </itemizedlist>
    </para>
    
    &postconditions;
    <para>
      <itemizedlist>
	<listitem>no user interface is open on the instance</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem>kOfxStatOK, the action was trapped and all was well</listitem>
	<listitem>kOfxStatReplyDefault, the action was ignored</listitem>
	<listitem>kOfxStatErrFatal, </listitem>
	<listitem>kOfxStatFailed, something went wrong, but no error code appropriate, the plugin should to post a message</listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="kOfxImageEffectActionDescribeInContext"><title >The Describe In Context Action</title>
    <blockquote><programlisting>
	#include "ofxImageEffect.h"
	#define kOfxImageEffectActionDescribeInContext  "OfxImageEffectActionDescribeInContext"</programlisting></blockquote>
    
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the context descriptor, cast to an <code>OfxImageEffectHandle</code>, this may
	  or may not be the same as passed to <link linkend="kOfxActionDescribe"><code>kOfxActionDescribe</code></link>.</listitem>
	<listitem><code>inArgs</code> has the following property...
	  <itemizedlist>
	    <listitem><link linkend="kOfxImageEffectPropContext"><code>kOfxImageEffectPropContext</code></link> the context being described.</listitem>
	  </itemizedlist>
	</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    
    &description;
    <para>
      This action is unique to OFX Image Effect plug-ins. Because a plugin is able to exhibit different behaviour depending on the context of use, each separate context will need to be described individually. It is within this action that image effects describe which parameters and input clips it requires.
    </para>
    <para>
      This action will be called multiple times, one for each of the contexts the plugin says it is capable of implementing. If a host does not support a certain context, then it need not call <code>kOfxImageEffectActionDescribeInContext</code> for that context.
    </para>
        
    <para>
      This action <emphasis>must</emphasis> be trapped, it is not optional.
    </para>
    
    &preconditions;
    <para>
      <itemizedlist>
	<listitem>kOfxActionDescribe has been called on the descriptor handle,</listitem>
	<listitem>kOfxActionCreateInstance has <emphasis>not</emphasis> been called,</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem>kOfxStatOK, the action was trapped and all was well</listitem>
	<listitem>kOfxStatErrMissingHostFeature, in which the context will be ignored by the host, the plugin may post a message</listitem>
	<listitem>kOfxStatErrMemory, in which case the action may be called again after a memory purge</listitem>
	<listitem>kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message</listitem>
	<listitem>kOfxStatErrFatal</listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="kOfxImageEffectActionGetRegionOfDefinition"><title >The Get Region of Definition Action</title> 
    <blockquote><programlisting>
	#include "ofxImageEffect.h"
	#define kOfxImageEffectActionGetRegionOfDefinition        "OfxImageEffectActionGetRegionOfDefinition"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the instance, cast to an <code>OfxImageEffectHandle</code>,</listitem>
	<listitem><code>inArgs</code> has the following properties...
	  <itemizedlist>
	    <listitem><link linkend="kOfxPropTime"><code>kOfxPropTime</code></link> the effect time for which a region of definition is being requested,</listitem>
	    <listitem><link linkend="kOfxImageEffectPropRenderScale"><code>kOfxImageEffectPropRenderScale</code></link> the render scale that should be used in any calculations in this action,</listitem>
	  </itemizedlist>
	</listitem>
	<listitem><code>outArgs</code>  has the following property which the plug-in may set...
	  <itemizedlist>
	    <listitem><link linkend="kOfxImageEffectPropRegionOfDefinition"><code>kOfxImageEffectPropRegionOfDefinition</code></link>, the calculated region of definition, initially set by the host to the default RoD (see below), in Canonical Coordinates.</listitem>
	  </itemizedlist>
	</listitem>
      </itemizedlist>
    </para>
    
    &description;
    <para>
      The region of definition for an image effect is the rectangular section of the 2D image plane that it is capable of filling, given the state of its input clips and parameters. This action is used to calculate the RoD for a plugin instance at a given frame. For more details on regions of definition see <link linkend="ImageEffectArchitectures">Image Effect Architectures</link>.
    </para>
    <para>
      Note that hosts that have constant sized imagery need not call this action, only hosts that allow image sizes to vary need call this.
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem>kOfxStatOK, , the action was trapped and the RoD was set in the <code>outArgs</code> property set</listitem>
	<listitem>kOfxStatReplyDefault, the action was not trapped and the host should use the default values</listitem>
	<listitem>kOfxStatErrMemory, in which case the action may be called again after a memory purge</listitem>
	<listitem>kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message</listitem>
	<listitem>kOfxStatErrFatal</listitem>
      </itemizedlist>
    </para>
    
    &defaultAction;
    <para>
      If the effect did not trap this, it means the host should use the default RoD instead, which depends on the context. This is...
      <itemizedlist>
	<listitem>generator context  - defaults to the project window,</listitem>
	<listitem>filter and paint contexts   - defaults to the RoD of the 'Source' input clip at the given time,</listitem>
	<listitem>transition context - defaults to the union of the RoDs of the 'SourceFrom' and 'SourceTo' input clips at the given time,</listitem>
	<listitem>general context    - defaults to the union of the RoDs of all the non optional input clips 
	  and the 'Source' input clip (if it exists and it is connected)
	  at the given time, if none exist, then it is the project window</listitem>
	<listitem>retimer context    - defaults to the union of the RoD of the 'Source' input clip at the frame directly preceding the
	  value of the 'SourceTime' double parameter and the frame directly after it</listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="kOfxImageEffectActionGetRegionsOfInterest"><title >The Get Regions Of Interest Action</title>
    <blockquote><programlisting>
	#include "ofxImageEffect.h"
	#define kOfxImageEffectActionGetRegionsOfInterest         "OfxImageEffectActionGetRegionsOfInterest"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the instance, cast to an <code>OfxImageEffectHandle</code>,</listitem>
	<listitem><code>inArgs</code> has the following properties...
	  <itemizedlist>
	    <listitem><link linkend="kOfxPropTime"><code>kOfxPropTime</code></link> the effect time for which a region of definition is being requested,</listitem>
	    
	    <listitem><link linkend="kOfxImageEffectPropRenderScale"><code>kOfxImageEffectPropRenderScale</code></link> the render scale that should be used in any calculations in this action,</listitem>
	    <listitem><link linkend="kOfxImageEffectPropRegionOfInterest"><code>kOfxImageEffectPropRegionOfInterest</code></link> the region to be rendered in the output image, in Canonical Coordinates.</listitem>
	  </itemizedlist>
	</listitem>
	<listitem><code>outArgs</code> has a set of 4 dimensional double properties, one for each of the input clips to the effect. The properties are each named "OfxImageClipPropRoI_" with the clip name post pended, for example "OfxImageClipPropRoI_Source". These are initialised to the default RoI. </listitem>
      </itemizedlist>
    </para>
    
    &description;
    <para>
      This action allows a host to ask an effect, given a region I want to render, what region do you need from each of your input clips. In that way, depending on the host architecture, a host can fetch the minimal amount of the image needed as input. Note that there is a region of interest to be set in <code>outArgs</code> for each input clip that exists on the effect. Form more details see <link linkend="ImageEffectArchitectures">Image Effect Architectures</link>.
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem>kOfxStatOK, the action was trapped and at least one RoI was set in the <code>outArgs</code> property set</listitem>
	<listitem>kOfxStatReplyDefault, the action was not trapped and the host should use the default values</listitem>
	<listitem>kOfxStatErrMemory, in which case the action may be called again after a memory purge</listitem>
	<listitem>kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message</listitem>
	<listitem>kOfxStatErrFatal</listitem>
      </itemizedlist>
    </para>
    
    &defaultAction;
    <para>
      The default RoI is simply the value passed in on the <link linkend="kOfxImageEffectPropRegionOfInterest"><code>kOfxImageEffectPropRegionOfInterest</code></link> <code>inArgs</code> property set. All the RoIs in the <code>outArgs</code> property set must initialised to this value before the action is called.
    </para>
  </section>
  
  <section id="kOfxImageEffectActionGetFramesNeeded"><title >The Get Frames Needed Action</title>
    <blockquote><programlisting>
	#include "ofxImageEffect.h"
	#define kOfxImageEffectActionGetFramesNeeded              "OfxImageEffectActionGetFramesNeeded"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the instance, cast to an <code>OfxImageEffectHandle</code>,</listitem>
	<listitem><code>inArgs</code> has the following property...
	  <itemizedlist>
	    <listitem><link linkend="kOfxPropTime"><code>kOfxPropTime</code></link> the effect time for which we need to calculate the frames needed on input</listitem>
	  </itemizedlist>
	</listitem>
	<listitem><code>outArgs</code>  has a set of properties, one for each input clip, named "OfxImageClipPropFrameRange_" with the name of the clip post-pended. For example "OfxImageClipPropFrameRange_Source". All these properties are multi-dimensional doubles, with the dimension is a multiple of two. Each pair of values indicates a continuous range of frames that is needed on the given input. They are all initalised to the default value.
	</listitem>
      </itemizedlist>
    </para>
    
    &description;
    <para>
      This action lets the host ask the effect what frames are needed from each input clip to process a given frame. For example a temporal based degrainer may need several frames around the frame to render to do its work.
    </para>
    <para>
      This action need only ever be called if the plugin has set the <link linkend="kOfxImageEffectPropTemporalClipAccess"><code>kOfxImageEffectPropTemporalClipAccess</code></link> property on the plugin descriptor to be true. Otherwise the host assumes that the only frame needed from the inputs is the current one and this action is not called.
    </para>
    <para>
      Note that each clip can have it's required frame range specified, and that you can specify discontinuous sets of ranges for each clip, for example...
      <blockquote><programlisting>
	  // The effect always needs the initial frame of the source as well as the previous and current frame
	  double rangeSource[4];
	  
	  // required ranges on the source
	  rangeSource[0] = 0; // we always need frame 0 of the source
	  rangeSource[1] = 0;
	  rangeSource[2] = currentFrame - 1; // we also need the previous and current frame on the source
	  rangeSource[3] = currentFrame;
	  
	  gPropHost->propSetDoubleN(outArgs, "OfxImageClipPropFrameRange_Source", 4, rangeSource); </programlisting></blockquote>
      
      Which sets two discontinuous range of frames from the 'Source' clip required as input.
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem>kOfxStatOK, the action was trapped and at least one frame range in the <code>outArgs</code> property set</listitem>
	<listitem>kOfxStatReplyDefault, the action was not trapped and the host should use the default values</listitem>
	<listitem>kOfxStatErrMemory, in which case the action may be called again after a memory purge</listitem>
	<listitem>kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message</listitem>
	<listitem>kOfxStatErrFatal</listitem>
      </itemizedlist>
    </para>
    
    &defaultAction;
    <para>
      The default frame range is simply the single frame, kOfxPropTime..kOfxPropTime, found on the <code>inArgs</code> property set. All the frame ranges in the <code>outArgs</code> property set must initialised to this value before the action is called.
    </para>
    
  </section>
  
  <section id="kOfxImageEffectActionIsIdentity"><title >The Is Identity Action</title>
    <blockquote><programlisting>
	#include "ofxImageEffect.h"
	#define kOfxImageEffectActionIsIdentity            "OfxImageEffectActionIsIdentity"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the instance, cast to an <code>OfxImageEffectHandle</code>,</listitem>
	<listitem><code>inArgs</code> has the following properties...
	  <itemizedlist>	      
	    <listitem><link linkend="kOfxPropTime"><code>kOfxPropTime</code></link> - the time at which to test for identity</listitem>
	    <listitem><link linkend="kOfxImageEffectPropFieldToRender"><code>kOfxImageEffectPropFieldToRender</code></link> - the field to test for identity</listitem>
	    <listitem><link linkend="kOfxImageEffectPropRenderWindow"><code>kOfxImageEffectPropRenderWindow</code></link> - the window (in \ref PixelCoordinates) to test for identity under</listitem>
	    <listitem><link linkend="kOfxImageEffectPropRenderScale"><code>kOfxImageEffectPropRenderScale</code></link> - the scale factor being applied to the images being renderred</listitem>
	  </itemizedlist>
	</listitem>
	
	<listitem><code>outArgs</code> has the following properties which the plugin can set...
	  <itemizedlist>	      
	    <listitem><link linkend="kOfxPropName"><code>kOfxPropName</code></link> this to the name of the clip that should be used if the effect is an identity transform, defaults to the empty string</listitem>
	    <listitem><link linkend="kOfxPropTime"><code>kOfxPropTime</code></link> the time to use from the indicated source clip as an identity image (allowing time slips to happen), defaults to the value in <code>kOfxPropTime</code> in inArgs</listitem>
	  </itemizedlist>
	</listitem>
      </itemizedlist>
    </para>
    
    &description;
    <para>
      Sometimes an effect can pass through an input uprocessed, for example a blur effect with a blur size of 0. This action can be called by a host before it attempts to render an effect to determine if it can simply copy input directly to output without having to call the render action on the effect.
    </para>
    
    <para>
      If the effect does not need to process any pixels, it should set the value of the <code>kOfxPropName</code> to the clip that the host should us as the output instead, and the <code>kOfxPropTime</code> property on <code>outArgs</code> to be the time at which the frame should be fetched from a clip.
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem>kOfxStatOK, the action was trapped and the effect should not have its render action called, the values in <code>outArgs</code> indicate what frame from which clip to use instead</listitem>
	<listitem>kOfxStatReplyDefault, the action was not trapped and the host should call the render action</listitem>
	<listitem>kOfxStatErrMemory, in which case the action may be called again after a memory purge</listitem>
	<listitem>kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message</listitem>
	<listitem>kOfxStatErrFatal</listitem>
      </itemizedlist>
    </para>
    
    &defaultAction;
    <para>
      The default action is to call the render action on the effect.
    </para>
  </section>
  
  <section id="kOfxImageEffectActionRender"><title >The Render Action</title>
    <blockquote><programlisting>
	#include "ofxImageEffect.h"
	#define kOfxImageEffectActionRender                "OfxImageEffectActionRender"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the instance, cast to an <code>OfxImageEffectHandle</code>,</listitem>
	<listitem><code>inArgs</code> has the following properties...
	  <itemizedlist>	      
	    <listitem><link linkend="kOfxPropTime"><code>kOfxPropTime</code></link> - the time at which to test for identity</listitem>
	    <listitem><link linkend="kOfxImageEffectPropFieldToRender"><code>kOfxImageEffectPropFieldToRender</code></link> - the field to test for identity</listitem>
	    <listitem><link linkend="kOfxImageEffectPropRenderWindow"><code>kOfxImageEffectPropRenderWindow</code></link> - the window (in \ref PixelCoordinates) to test for identity under</listitem>
	    <listitem><link linkend="kOfxImageEffectPropRenderScale"><code>kOfxImageEffectPropRenderScale</code></link> - the scale factor being applied to the images being renderred</listitem>
	    <listitem><link linkend="kOfxImageEffectPropSequentialRenderStatus"><code>kOfxImageEffectPropSequentialRenderStatus</code></link> - whether the effect is currently being rendered in strict frame order on a single instance</listitem>
	    <listitem><link linkend="kOfxImageEffectPropInteractiveRenderStatus"><code>kOfxImageEffectPropInteractiveRenderStatus</code></link> - if the render is in response to a user modifying the effect in an interactive session</listitem>
	    <listitem><link linkend="kOfxImageEffectPropRenderQualityDraft"><code>kOfxImageEffectPropRenderQualityDraft</code></link> - if the render should be done in draft mode (e.g. for faster scrubbing)</listitem>
	  </itemizedlist>
	</listitem>
	<listitem><code>outArgs</code> is redundant and should be set to NULL.</listitem>
      </itemizedlist>
    </para>
    
    &description;
    <para>
      This action is where an effect gets to push pixels and turn its input clips and parameter set into an output image. This is possibly quite complicated and covered in the <link linkend="RenderingEffects">Rendering Image Effects</link> chapter.
    </para>
    
    
    &preconditions;
    <para>
      <itemizedlist>
	<listitem>kOfxActionCreateInstance has been called on the instance</listitem>
	<listitem>kOfxImageEffectActionBeginSequenceRender has been called on the instance</listitem>
      </itemizedlist>
    </para>
    
    
    &postconditions;
    <para>
      <itemizedlist>
	<listitem>kOfxImageEffectActionEndSequenceRender action will be called on the instance</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem>kOfxStatOK, the effect rendered happily</listitem>
	<listitem>kOfxStatErrMemory, in which case the action may be called again after a memory purge</listitem>
	<listitem>kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message</listitem>
	<listitem>kOfxStatErrFatal</listitem>
      </itemizedlist>
    </para>
    
    &defaultAction;
    <para>
      The render action <emphasis>must</emphasis> be trapped by the plug-in, it cannot return kOfxStatReplyDefault. The pixels needs be pushed I'm afraid.
    </para>
    
  </section>
  
  <section id="kOfxImageEffectActionBeginSequenceRender"><title >The Begin Sequence Render Action</title>
    <blockquote><programlisting>
	#include "ofxImageEffect.h"
	#define kOfxImageEffectActionBeginSequenceRender   "OfxImageEffectActionBeginSequenceRender"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the instance, cast to an <code>OfxImageEffectHandle</code>,</listitem>
	<listitem><code>inArgs</code> has the following properties...
	  <itemizedlist>
	    <listitem><link linkend="kOfxImageEffectPropFrameRange"><code>kOfxImageEffectPropFrameRange</code></link> - the range of frames (inclusive) that will be renderred,</listitem>
	    <listitem><link linkend="kOfxImageEffectPropFrameStep"><code>kOfxImageEffectPropFrameStep</code></link>  - what is the step between frames, generally set to 1 (for full frame renders) or 0.5 (for fielded renders),</listitem>
	    <listitem><link linkend="kOfxPropIsInteractive"><code>kOfxPropIsInteractive</code></link>  - is this a single frame render due to user interaction in a GUI, or a proper full sequence render.</listitem>
	    <listitem><link linkend="kOfxImageEffectPropRenderScale"><code>kOfxImageEffectPropRenderScale</code></link>   - the scale factor to apply to images for this call</listitem>
	    <listitem><link linkend="kOfxImageEffectPropSequentialRenderStatus"><code>kOfxImageEffectPropSequentialRenderStatus</code></link> - whether the effect is currently being rendered in strict frame order on a single instance</listitem>
	    <listitem><link linkend="kOfxImageEffectPropInteractiveRenderStatus"><code>kOfxImageEffectPropInteractiveRenderStatus</code></link> - if the render is in response to a user modifying the effect in an interactive session</listitem>
	  </itemizedlist>
	</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    
    &description;
    <para>
      This action is passed to an image effect before it renders a range of frames. It is there to allow an effect to set things up for a long sequence of frames. Note that this is still called, even if only a single frame is being rendered in an interactive environment.
    </para>
    
    &preconditions;
    <para>
      <itemizedlist>
	<listitem>kOfxActionCreateInstance has been called on the instance</listitem>
      </itemizedlist>
    </para>
    
    &postconditions;
    <para>
      <itemizedlist>	  
	<listitem>kOfxImageEffectActionRender action will be called at least once on the instance</listitem>
	<listitem>kOfxImageEffectActionEndSequenceRender action will be called on the instance</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem>kOfxStatOK, the action was trapped and handled cleanly by the effect, </listitem>
	<listitem>kOfxStatReplyDefault, the action was not trapped, but all is well anyway,</listitem>
	<listitem>kOfxStatErrMemory, in which case the action may be called again after a memory purge,</listitem>
	<listitem>kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message,</listitem>
	<listitem>kOfxStatErrFatal</listitem>
      </itemizedlist>
    </para>
    
    
  </section>
  
  <section id="kOfxImageEffectActionEndSequenceRender"><title >The End Sequence Render Action</title>
    <blockquote><programlisting>
	#include "ofxImageEffect.h"
	#define kOfxImageEffectActionEndSequenceRender      "OfxImageEffectActionEndSequenceRender"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the instance, cast to an <code>OfxImageEffectHandle</code>,</listitem>
	<listitem><code>inArgs</code> has the following properties...
	  <itemizedlist>
	    <listitem><link linkend="kOfxImageEffectPropFrameRange"><code>kOfxImageEffectPropFrameRange</code></link> - the range of frames (inclusive) that will be renderred,</listitem>
	    <listitem><link linkend="kOfxImageEffectPropFrameStep"><code>kOfxImageEffectPropFrameStep</code></link>  - what is the step between frames, generally set to 1 (for full frame renders) or 0.5 (for fielded renders),</listitem>
	    <listitem><link linkend="kOfxPropIsInteractive"><code>kOfxPropIsInteractive</code></link>  - is this a single frame render due to user interaction in a GUI, or a proper full sequence render.</listitem>
	    <listitem><link linkend="kOfxImageEffectPropRenderScale"><code>kOfxImageEffectPropRenderScale</code></link>   - the scale factor to apply to images for this call</listitem>
	    <listitem><link linkend="kOfxImageEffectPropSequentialRenderStatus"><code>kOfxImageEffectPropSequentialRenderStatus</code></link> - whether the effect is currently being rendered in strict frame order on a single instance</listitem>
	    <listitem><link linkend="kOfxImageEffectPropInteractiveRenderStatus"><code>kOfxImageEffectPropInteractiveRenderStatus</code></link> - if the render is in response to a user modifying the effect in an interactive session</listitem>
	  </itemizedlist>
	</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    
    &description;
    <para>
      This action is passed to an image effect after is has rendered a range of frames. It is there to allow an effect to free resources after a long sequence of frame renders. Note that this is still called, even if only a single frame is being rendered in an interactive environment.
    </para>
    
    
    &preconditions;
    <para>
      <itemizedlist>
	<listitem>kOfxActionCreateInstance has been called on the instance</listitem>
	<listitem>kOfxImageEffectActionEndSequenceRender action was called on the instance</listitem>
	<listitem>kOfxImageEffectActionRender action was called at least once on the instance</listitem>
      </itemizedlist>
    </para>
    
    &postconditions;
    <para>
      <itemizedlist>	  
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem>kOfxStatOK, the action was trapped and handled cleanly by the effect, </listitem>
	<listitem>kOfxStatReplyDefault, the action was not trapped, but all is well anyway,</listitem>
	<listitem>kOfxStatErrMemory, in which case the action may be called again after a memory purge,</listitem>
	<listitem>kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message,</listitem>
	<listitem>kOfxStatErrFatal</listitem>
      </itemizedlist>
    </para>
    
  </section>
  
  <section id="kOfxImageEffectActionGetClipPreferences"><title>The Get Clip Preferences Action</title>
    <blockquote><programlisting>
	#include "ofxImageEffect.h"
	#define kOfxImageEffectActionGetClipPreferences       "OfxImageEffectActionGetClipPreferences"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the instance, cast to an <code>OfxImageEffectHandle</code>,</listitem>
	<listitem><code>inArgs</code> is redundant and is set to NULL.</listitem>
	<listitem><code>outArgs</code> has the following properties which the plugin can set...
	  <itemizedlist>
	    <listitem>a set of char * X 1 properties, one for each of the input clips currently attached and the output clip, labelled with "OfxImageClipPropComponents_" post pended with the clip's name. This must be set to one of the component types which the host supports and the effect stated it can accept on that input,</listitem>
	    <listitem>a set of char * X 1 properties, one for each of the input clips currently attached and the output clip, labelled with "OfxImageClipPropDepth_" post pended with the clip's name. This must be set to one of the pixel depths both the host and plugin supports,</listitem>
	    <listitem>a set of double X 1 properties, one for each of the input clips currently attached and the output clip, labelled with "OfxImageClipPropPAR_" post pended with the clip's name. This is the pixel aspect ratio of the input and output clips. This must be set to a positive non zero double value,</listitem>
	    
	    <listitem><link linkend="kOfxImageEffectPropFrameRate"><code>kOfxImageEffectPropFrameRate</code></link> , the frame rate of the output clip, this must be set to a positive non zero double value,</listitem>
	    <listitem><link linkend="kOfxImageClipPropFieldOrder"><code>kOfxImageClipPropFieldOrder</code></link> , the fielding of the output clip,</listitem>
	    <listitem><link linkend="kOfxImageEffectPropPreMultiplication"><code>kOfxImageEffectPropPreMultiplication</code></link> , the premultiplication of the output clip,</listitem>
	    <listitem><link linkend="kOfxImageClipPropContinuousSamples"><code>kOfxImageClipPropContinuousSamples</code></link>, whether the output clip can produce different images at non-frame intervals, defaults to false,</listitem>
	    <listitem><link linkend="kOfxImageEffectFrameVarying"><code>kOfxImageEffectFrameVarying</code></link>, whether the output clip can produces different images at different times, even if all parameters and inputs are constant, defaults to false.</listitem>
	  </itemizedlist>
	</listitem>
      </itemizedlist>
    </para>
    
    &description;
    <para>
      This action allows a plugin to dynamically specify its preferences for input and output clips. Please see <link linkend="ImageEffectClipPreferences">Image Effect Clip Preferences</link> for more details on the behaviour. Clip preferences are constant for the duration of an effect, so this action need only be called once per clip, not once per frame. 
    </para>
    <para>This should be called once after creation of an instance, each time an input clip is changed, and whenever a parameter named in the <link linkend="kOfxImageEffectPropClipPreferencesSlaveParam"><code>kOfxImageEffectPropClipPreferencesSlaveParam</code></link> has its value changed.
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem>kOfxStatOK, the action was trapped and at least one of the properties in the <code>outArgs</code> was changed from its default value</listitem>
	<listitem>kOfxStatReplyDefault, the action was not trapped and the host should use the default values</listitem>
	<listitem>kOfxStatErrMemory, in which case the action may be called again after a memory purge</listitem>
	<listitem>kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message</listitem>
	<listitem>kOfxStatErrFatal</listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="kOfxImageEffectActionGetTimeDomain"><title>The Get Time Domain Action</title>
    <blockquote><programlisting>
	#include "ofxImageEffect.h"
	#define kOfxImageEffectActionGetTimeDomain                "OfxImageEffectActionGetTimeDomain"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the instance, cast to an <code>OfxImageEffectHandle</code>,</listitem>
	<listitem><code>inArgs</code> is redundant and is null</listitem>
	<listitem><code>outArgs</code> has the following property
	  <itemizedlist>
	    <listitem><link linkend="kOfxImageEffectPropFrameRange"><code>kOfxImageEffectPropFrameRange</code></link> - the frame range an effect can produce images for</listitem>
	  </itemizedlist>
	</listitem>
      </itemizedlist>
    </para>
    
    &description;
    <para>
      This action allows a host to ask an effect what range of frames it can produce images over. Only effects instantiated in the <link linkend="GeneralContext">General Context</link>can have this called on them. In all other the host is in strict control over the temporal duration of the effect.
    </para>
    
    &preconditions;
    <para>
      <itemizedlist>
	<listitem>kOfxActionCreateInstance has been called on the instance</listitem>
	<listitem>the effect instance has been created in the general effect context</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem>kOfxStatOK, the action was trapped and the kOfxImageEffectPropFrameRange was set in the <code>outArgs</code> property set</listitem>
	<listitem>kOfxStatReplyDefault, the action was not trapped and the host should use the default value</listitem>
	<listitem>kOfxStatErrMemory, in which case the action may be called again after a memory purge</listitem>
	<listitem>kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message</listitem>
	<listitem>kOfxStatErrFatal</listitem>
      </itemizedlist>
    </para>
    
    &defaultAction;
    <para> The default is,
      <itemizedlist>
	<listitem>the union of all the frame ranges of the non optional input clips,</listitem>
	<listitem>infinite if there are no non optional input clips.</listitem>
      </itemizedlist>
    </para>
    
  </section>
  
</chapter>
  
