
<refentry id="OfxImageEffectSuiteV1">
  <refmeta>
    <refentrytitle><type>OfxImageEffectSuiteV1</type></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxImageEffectSuiteV1</function></refname>
    <refpurpose>The OFX suite for image effects</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
     <blockquote><programlisting>
#include "ofxImageEffect.h"
typedef struct OfxImageEffectSuiteV1 {  
  OfxStatus (*getPropertySet)(OfxImageEffectHandle imageEffect,
			      OfxPropertySetHandle *propHandle);
  OfxStatus (*getParamSet)(OfxImageEffectHandle imageEffect,
			   OfxParamSetHandle *paramSet);
  OfxStatus (*clipDefine)(OfxImageEffectHandle imageEffect,
			  const char *name,	 
			  OfxPropertySetHandle *propertySet);
  OfxStatus (*clipGetHandle)(OfxImageEffectHandle imageEffect,
			     const char *name,
			     OfxImageClipHandle *clip,
			     OfxPropertySetHandle *propertySet);
  OfxStatus (*clipGetPropertySet)(OfxImageClipHandle clip,
				  OfxPropertySetHandle *propHandle);
  OfxStatus (*clipGetImage)(OfxImageClipHandle clip,
			    OfxTime       time,
			    const OfxRectD     *region,
			    OfxPropertySetHandle   *imageHandle);
  OfxStatus (*clipReleaseImage)(OfxPropertySetHandle imageHandle);
  OfxStatus (*clipGetRegionOfDefinition)(OfxImageClipHandle clip,
					 OfxTime time,
					 OfxRectD *bounds);
  int (*abort)(OfxImageEffectHandle imageEffect);
  OfxStatus (*imageMemoryAlloc)(OfxImageEffectHandle instanceHandle, 
				size_t nBytes,
				OfxImageMemoryHandle *memoryHandle);
  OfxStatus (*imageMemoryFree)(OfxImageMemoryHandle memoryHandle);
  OfxStatus (*imageMemoryLock)(OfxImageMemoryHandle memoryHandle,
			       void **returnedPtr);
  OfxStatus (*imageMemoryUnlock)(OfxImageMemoryHandle memoryHandle);
} OfxImageEffectSuiteV1;

</programlisting></blockquote>
     </refsynopsisdiv>
    <refsect1>
      <title>Description</title><para>
This suite provides the functions needed by a plugin to defined and use an image effect plugin.
</para>
    </refsect1>
</refentry>

<refentry id="OfxImageEffectSuiteV1_getPropertySet">
  <refmeta>
    <refentrytitle><function>OfxImageEffectSuiteV1::getPropertySet</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxImageEffectSuiteV1::getPropertySet</function></refname>
       <refpurpose>Retrieves the property set for the given image effect</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxImageEffect.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*getPropertySet)</function></funcdef>
              <paramdef>OfxImageEffectHandle<parameter>imageEffect</parameter></paramdef>
              <paramdef>OfxPropertySetHandle *<parameter>propHandle</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>imageEffect - image effect to get the property set for
</listitem>
<listitem>propHandle - pointer to a the property set pointer, value is returned here
</listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
The property handle is for the duration of the image effect handle.
</para>

  </refsect2>

  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem><link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>       - the property set was found and returned</listitem>
  <listitem><link linkend="kOfxStatErrBadHandle"><code>kOfxStatErrBadHandle</code></link>  - if the paramter handle was invalid</listitem>
  <listitem><link linkend="kOfxStatErrUnknown"><code>kOfxStatErrUnknown</code></link>    - if the type is unknown</listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>

<refentry id="OfxImageEffectSuiteV1_getParamSet">
  <refmeta>
    <refentrytitle><function>OfxImageEffectSuiteV1::getParamSet</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxImageEffectSuiteV1::getParamSet</function></refname>
       <refpurpose>Retrieves the parameter set for the given image effect</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxImageEffect.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*getParamSet)</function></funcdef>
              <paramdef>OfxImageEffectHandle<parameter>imageEffect</parameter></paramdef>
              <paramdef>OfxParamSetHandle *<parameter>paramSet</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>imageEffect - image effect to get the property set for
</listitem>
<listitem>paramSet - pointer to a the parameter set, value is returned here
</listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
The param set handle is valid for the lifetime of the image effect handle.
</para>

  </refsect2>

  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem><link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>       - the property set was found and returned</listitem>
  <listitem><link linkend="kOfxStatErrBadHandle"><code>kOfxStatErrBadHandle</code></link>  - if the paramter handle was invalid</listitem>
  <listitem><link linkend="kOfxStatErrUnknown"><code>kOfxStatErrUnknown</code></link>    - if the type is unknown</listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>

<refentry id="OfxImageEffectSuiteV1_clipDefine">
  <refmeta>
    <refentrytitle><function>OfxImageEffectSuiteV1::clipDefine</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxImageEffectSuiteV1::clipDefine</function></refname>
       <refpurpose>Define a clip to the effect. </refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxImageEffect.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*clipDefine)</function></funcdef>
              <paramdef>OfxImageEffectHandle<parameter>imageEffect</parameter></paramdef>
              <paramdef>const char *<parameter>name</parameter></paramdef>
              <paramdef>OfxPropertySetHandle *<parameter>propertySet</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>imageEffect - </listitem>
<listitem>name - unique name of the clip to define
</listitem>
<listitem>propertySet - a property handle for the clip descriptor will be returned here
</listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
This function defines a clip to a host, the returned property set is used to describe
various aspects of the clip to the host. Note that this does not create a clip instance.
</para>
<para>
\pre

<itemizedlist>
  <listitem>we are inside the describe in context action.</listitem>
</itemizedlist>
</para>

  </refsect2>

</refentry>

<refentry id="OfxImageEffectSuiteV1_clipGetHandle">
  <refmeta>
    <refentrytitle><function>OfxImageEffectSuiteV1::clipGetHandle</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxImageEffectSuiteV1::clipGetHandle</function></refname>
       <refpurpose>Get the propery handle of the named input clip in the given instance </refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxImageEffect.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*clipGetHandle)</function></funcdef>
              <paramdef>OfxImageEffectHandle<parameter>imageEffect</parameter></paramdef>
              <paramdef>const char *<parameter>name</parameter></paramdef>
              <paramdef>OfxImageClipHandle *<parameter>clip</parameter></paramdef>
              <paramdef>OfxPropertySetHandle *<parameter>propertySet</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>imageEffect - an instance handle to the plugin
</listitem>
<listitem>name - name of the clip, previously used in a clip define call
</listitem>
<listitem>clip - where to return the clip
</listitem>
<listitem>propertySet - if not null, the descriptor handle for a parameter's property set will be placed here.
</listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
The propertySet will have the same value as would be returned by <link linkend="OfxImageEffectSuiteV1_clipGetPropertySet"><code>OfxImageEffectSuiteV1::clipGetPropertySet</code></link>
</para>
<para>
This return a clip handle for the given instance, note that this will <emphasis> m</emphasis> not be the same as the
clip handle returned by clipDefine and will be distanct to clip handles in any other instance
of the plugin.
</para>
<para>
Not a valid call in any of the describe actions.
</para>
<para>
\pre

<itemizedlist>
  <listitem>create instance action called,</listitem>
  <listitem><emphasis> name</emphasis> passed to clipDefine for this context,</listitem>
  <listitem>not inside describe or describe in context actions.</listitem>
</itemizedlist>
</para>
<para>
\post

<itemizedlist>
  <listitem>handle will be valid for the life time of the instance.</listitem>
</itemizedlist>
</para>

  </refsect2>

</refentry>

<refentry id="OfxImageEffectSuiteV1_clipGetPropertySet">
  <refmeta>
    <refentrytitle><function>OfxImageEffectSuiteV1::clipGetPropertySet</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxImageEffectSuiteV1::clipGetPropertySet</function></refname>
       <refpurpose>Retrieves the property set for a given clip</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxImageEffect.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*clipGetPropertySet)</function></funcdef>
              <paramdef>OfxImageClipHandle<parameter>clip</parameter></paramdef>
              <paramdef>OfxPropertySetHandle *<parameter>propHandle</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>clip - clip effect to get the property set for
</listitem>
<listitem>propHandle - pointer to a the property set handle, value is returedn her
</listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
The property handle is valid for the lifetime of the clip, which is generally the lifetime of the instance.
</para>

  </refsect2>

  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem><link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>       - the property set was found and returned</listitem>
  <listitem><link linkend="kOfxStatErrBadHandle"><code>kOfxStatErrBadHandle</code></link>  - if the paramter handle was invalid</listitem>
  <listitem><link linkend="kOfxStatErrUnknown"><code>kOfxStatErrUnknown</code></link>    - if the type is unknown</listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>

<refentry id="OfxImageEffectSuiteV1_clipGetImage">
  <refmeta>
    <refentrytitle><function>OfxImageEffectSuiteV1::clipGetImage</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxImageEffectSuiteV1::clipGetImage</function></refname>
       <refpurpose>Get a handle for an image in a clip at the indicated time and indicated region</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxImageEffect.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*clipGetImage)</function></funcdef>
              <paramdef>OfxImageClipHandle<parameter>clip</parameter></paramdef>
              <paramdef>OfxTime      <parameter>time</parameter></paramdef>
              <paramdef>const OfxRectD     *<parameter>region</parameter></paramdef>
              <paramdef>OfxPropertySetHandle   *<parameter>imageHandle</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>clip - the clip to extract the image from
</listitem>
<listitem>time - time to fetch the image at
</listitem>
<listitem>region - region to fetch the image from (optional, set to NULL to get a 'default' region)
this is in the <link linkend="CanonicalCoordinates">CanonicalCoordinates</link>. 
</listitem>
<listitem>imageHandle - property set containing the image's data
</listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
An image is fetched from a clip at the indicated time for the given region and returned in the imageHandle.
</para>
<para>
If the <emphasis> region</emphasis> parameter is not set to NULL, then it will be clipped to the clip's Region of Definition for the given time. The returned image will be <emphasis> m</emphasis> at <emphasis> m</emphasis> least as big as this region. If the region parameter is not set, then the region fetched will be at least the Region of Interest the effect has previously specified, clipped the clip's Region of Definition.
</para>
<para>
If clipGetImage is called twice with the same parameters, then two separate image handles will be returned, each of which must be release. The underlying implementation could share image data pointers and use reference counting to maintain them.
</para>
<para>
\pre

<itemizedlist>
  <listitem>clip was returned by clipGetHandle</listitem>
</itemizedlist>
</para>
<para>
\post

<itemizedlist>
  <listitem>image handle is only valid for the duration of the action clipGetImage is called in</listitem>
  <listitem>image handle to be disposed of by clipReleaseImage before the action returns</listitem>
</itemizedlist>
</para>

  </refsect2>

  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem><link linkend="kOfxStatOK"><code>kOfxStatOK</code></link> - the image was successfully fetched and returned in the handle,</listitem>
  <listitem><link linkend="kOfxStatFailed"><code>kOfxStatFailed</code></link> - the image could not be fetched because it does not exist in the clip at the indicated time and/or region, the plugin</listitem>
</itemizedlist>
should continue operation, but assume the image was black and transparent.

<itemizedlist>
  <listitem><link linkend="kOfxStatErrBadHandle"><code>kOfxStatErrBadHandle</code></link> - the clip handle was invalid,</listitem>
  <listitem><link linkend="kOfxStatErrMemory"><code>kOfxStatErrMemory</code></link> - the host had not enough memory to complete the operation, plugin should abort whatever it was doing.</listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>

<refentry id="OfxImageEffectSuiteV1_clipReleaseImage">
  <refmeta>
    <refentrytitle><function>OfxImageEffectSuiteV1::clipReleaseImage</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxImageEffectSuiteV1::clipReleaseImage</function></refname>
       <refpurpose>Releases the image handle previously returned by clipGetImage</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxImageEffect.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*clipReleaseImage)</function></funcdef>
              <paramdef>OfxPropertySetHandle<parameter>imageHandle</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>imageHandle - </listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
\pre

<itemizedlist>
  <listitem>imageHandle was returned by clipGetImage</listitem>
</itemizedlist>
</para>
<para>
\post

<itemizedlist>
  <listitem>all operations on imageHandle will be invalid</listitem>
</itemizedlist>
</para>

  </refsect2>

  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem><link linkend="kOfxStatOK"><code>kOfxStatOK</code></link> - the image was successfully fetched and returned in the handle,</listitem>
  <listitem><link linkend="kOfxStatErrBadHandle"><code>kOfxStatErrBadHandle</code></link> - the image handle was invalid,</listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>

<refentry id="OfxImageEffectSuiteV1_clipGetRegionOfDefinition">
  <refmeta>
    <refentrytitle><function>OfxImageEffectSuiteV1::clipGetRegionOfDefinition</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxImageEffectSuiteV1::clipGetRegionOfDefinition</function></refname>
       <refpurpose>Returns the spatial region of definition of the clip at the given time</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxImageEffect.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*clipGetRegionOfDefinition)</function></funcdef>
              <paramdef>OfxImageClipHandle<parameter>clip</parameter></paramdef>
              <paramdef>OfxTime<parameter>time</parameter></paramdef>
              <paramdef>OfxRectD *<parameter>bounds</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>clip - </listitem>
<listitem>time - time to fetch the image at
</listitem>
<listitem>bounds - </listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
An image is fetched from a clip at the indicated time for the given region and returned in the imageHandle.
</para>
<para>
If the <emphasis> region</emphasis> parameter is not set to NULL, then it will be clipped to the clip's Region of Definition for the given time. The returned image will be <emphasis> m</emphasis> at <emphasis> m</emphasis> least as big as this region. If the region parameter is not set, then the region fetched will be at least the Region of Interest the effect has previously specified, clipped the clip's Region of Definition.
</para>
<para>
\pre

<itemizedlist>
  <listitem>clipHandle was returned by clipGetHandle</listitem>
</itemizedlist>
</para>
<para>
\post

<itemizedlist>
  <listitem>bounds will be filled the RoD of the clip at the indicated time</listitem>
</itemizedlist>
</para>

  </refsect2>

  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem><link linkend="kOfxStatOK"><code>kOfxStatOK</code></link> - the image was successfully fetched and returned in the handle,</listitem>
  <listitem><link linkend="kOfxStatFailed"><code>kOfxStatFailed</code></link> - the image could not be fetched because it does not exist in the clip at the indicated time, the plugin</listitem>
</itemizedlist>
should continue operation, but assume the image was black and transparent.

<itemizedlist>
  <listitem><link linkend="kOfxStatErrBadHandle"><code>kOfxStatErrBadHandle</code></link> - the clip handle was invalid,</listitem>
  <listitem><link linkend="kOfxStatErrMemory"><code>kOfxStatErrMemory</code></link> - the host had not enough memory to complete the operation, plugin should abort whatever it was doing.</listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>

<refentry id="OfxImageEffectSuiteV1_abort">
  <refmeta>
    <refentrytitle><function>OfxImageEffectSuiteV1::abort</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxImageEffectSuiteV1::abort</function></refname>
       <refpurpose>Returns whether to abort processing or not.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxImageEffect.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>int</typename><function>(*abort)</function></funcdef>
              <paramdef>OfxImageEffectHandle<parameter>imageEffect</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>imageEffect - instance of the image effect
</listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
A host may want to signal to a plugin that it should stop whatever rendering it is doing and start again. 
Generally this is done in interactive threads in response to users tweaking some parameter.
</para>
<para>
This function indicates whether a plugin should stop whatever processing it is doing.
</para>

  </refsect2>

  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem>0 if the effect should continue whatever processing it is doing</listitem>
  <listitem>1 if the effect should abort whatever processing it is doing  </listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>

<refentry id="OfxImageEffectSuiteV1_imageMemoryAlloc">
  <refmeta>
    <refentrytitle><function>OfxImageEffectSuiteV1::imageMemoryAlloc</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxImageEffectSuiteV1::imageMemoryAlloc</function></refname>
       <refpurpose>Allocate memory from the host's image memory pool</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxImageEffect.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*imageMemoryAlloc)</function></funcdef>
              <paramdef>OfxImageEffectHandle<parameter>instanceHandle</parameter></paramdef>
              <paramdef>size_t<parameter>nBytes</parameter></paramdef>
              <paramdef>OfxImageMemoryHandle *<parameter>memoryHandle</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>instanceHandle - effect instance to associate with this memory allocation, may be NULL.
</listitem>
<listitem>nBytes - the number of bytes to allocate
</listitem>
<listitem>memoryHandle - pointer to the memory handle where a return value is placed
</listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
Memory handles allocated by this should be freed by <link linkend="OfxImageEffectSuiteV1_imageMemoryFree"><code>OfxImageEffectSuiteV1::imageMemoryFree</code></link>. 
To access the memory behind the handle you need to call  <link linkend="OfxImageEffectSuiteV1_imageMemoryLock"><code>OfxImageEffectSuiteV1::imageMemoryLock</code></link>.
</para>
<para>
See <link linkend="ImageEffectsMemoryAllocation">ImageEffectsMemoryAllocation</link>.
</para>

  </refsect2>

  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem>kOfxStatOK if all went well, a valid memory handle is placed in <emphasis> memoryHandle</emphasis></listitem>
  <listitem>kOfxStatErrBadHandle if instanceHandle is not valid, memoryHandle is set to NULL</listitem>
  <listitem>kOfxStatErrMemory if there was not enough memory to satisfy the call, memoryHandle is set to NULL</listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>

<refentry id="OfxImageEffectSuiteV1_imageMemoryFree">
  <refmeta>
    <refentrytitle><function>OfxImageEffectSuiteV1::imageMemoryFree</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxImageEffectSuiteV1::imageMemoryFree</function></refname>
       <refpurpose>Frees a memory handle and associated memory.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxImageEffect.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*imageMemoryFree)</function></funcdef>
              <paramdef>OfxImageMemoryHandle<parameter>memoryHandle</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>memoryHandle - memory handle returned by imageMemoryAlloc
</listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
This function frees a memory handle and associated memory that was previously allocated via <link linkend="OfxImageEffectSuiteV1_imageMemoryAlloc"><code>OfxImageEffectSuiteV1::imageMemoryAlloc</code></link>
</para>
<para>
If there are outstanding locks, these are ignored and the handle and memory are freed anyway.
</para>
<para>
See <link linkend="ImageEffectsMemoryAllocation">ImageEffectsMemoryAllocation</link>.
</para>

  </refsect2>

  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem>kOfxStatOK if the memory was cleanly deleted</listitem>
  <listitem>kOfxStatErrBadHandle if the value of <emphasis> memoryHandle</emphasis> was not a valid pointer returned by <link linkend="OfxImageEffectSuiteV1_imageMemoryAlloc"><code>OfxImageEffectSuiteV1::imageMemoryAlloc</code></link></listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>

<refentry id="OfxImageEffectSuiteV1_imageMemoryLock">
  <refmeta>
    <refentrytitle><function>OfxImageEffectSuiteV1::imageMemoryLock</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxImageEffectSuiteV1::imageMemoryLock</function></refname>
       <refpurpose>Lock the memory associated with a memory handle and make it available for use.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxImageEffect.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*imageMemoryLock)</function></funcdef>
              <paramdef>OfxImageMemoryHandle<parameter>memoryHandle</parameter></paramdef>
              <paramdef>void **<parameter>returnedPtr</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>memoryHandle - memory handle returned by imageMemoryAlloc
</listitem>
<listitem>returnedPtr - where to the pointer to the locked memory
</listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
This function locks them memory associated with a memory handle and returns a pointer to it. The memory will be 16 byte aligned, to allow use of vector operations.
</para>
<para>
Note that memory locks and unlocks nest.
</para>
<para>
After the first lock call, the contents of the memory pointer to by <emphasis> returnedPtr</emphasis> is undefined. All subsequent calls to lock will return memory with the same contents as  the previous call.
</para>
<para>
Also, if unlocked, then relocked, the memory associated with a memory handle may be at a different address.
</para>
<para>
See also <link linkend="OfxImageEffectSuiteV1_imageMemoryUnlock"><code>OfxImageEffectSuiteV1::imageMemoryUnlock</code></link> and <link linkend="ImageEffectsMemoryAllocation">ImageEffectsMemoryAllocation</link>.
</para>

  </refsect2>

  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem>kOfxStatOK if the memory was locked, a pointer is placed in <emphasis> returnedPtr</emphasis></listitem>
  <listitem>kOfxStatErrBadHandle if the value of <emphasis> memoryHandle</emphasis> was not a valid pointer returned by <link linkend="OfxImageEffectSuiteV1_imageMemoryAlloc"><code>OfxImageEffectSuiteV1::imageMemoryAlloc</code></link>, null is placed in <emphasis> returnedPtr</emphasis></listitem>
  <listitem>kOfxStatErrMemory if there was not enough memory to satisfy the call, <emphasis> returnedPtr</emphasis> is set to NULL</listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>

<refentry id="OfxImageEffectSuiteV1_imageMemoryUnlock">
  <refmeta>
    <refentrytitle><function>OfxImageEffectSuiteV1::imageMemoryUnlock</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxImageEffectSuiteV1::imageMemoryUnlock</function></refname>
       <refpurpose>Unlock allocated image data</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxImageEffect.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*imageMemoryUnlock)</function></funcdef>
              <paramdef>OfxImageMemoryHandle<parameter>memoryHandle</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>memoryHandle - </listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
This function unlocks a previously locked memory handle. Once completely unlocked, memory associated with a memoryHandle is no longer available for use. Attempting to use it results in undefined behaviour.
</para>
<para>
Note that locks and unlocks nest, and to fully unlock memory you need to match the count of locks placed upon it. 
</para>
<para>
Also note, if you unlock a completely unlocked handle, it has no effect (ie: the lock count can't be negative).
</para>
<para>
If unlocked, then relocked, the memory associated with a memory handle may be at a different address, however the contents will remain the same.
</para>
<para>
See also <link linkend="OfxImageEffectSuiteV1_imageMemoryLock"><code>OfxImageEffectSuiteV1::imageMemoryLock</code></link> and <link linkend="ImageEffectsMemoryAllocation">ImageEffectsMemoryAllocation</link>.
</para>

  </refsect2>

  <refsect2>
    <title>Returns</title>
      <para>

<itemizedlist>
  <listitem>kOfxStatOK if the memory was unlocked cleanly,</listitem>
  <listitem>kOfxStatErrBadHandle if the value of <emphasis> memoryHandle</emphasis> was not a valid pointer returned by <link linkend="OfxImageEffectSuiteV1_imageMemoryAlloc"><code>OfxImageEffectSuiteV1::imageMemoryAlloc</code></link>, null is placed in <emphasis> returnedPtr</emphasis></listitem>
</itemizedlist>
</para>

  </refsect2>
</refentry>
