Output colourspace negotiation action

A new action, OfxImageEffectActionGetOutputColourspace, allows the host to specify its preferred colourspaces for the plug-in’s output clip, and for the plug-in to specify the colourspace it selected.

OfxImageEffectActionGetClipPreferences now mentions that the plug-in can specify input clip colourspace preferences in this action.

Signed-off-by: John-Paul Smith <jps@borisfx.com>

include/ofxColour.h

@@ -195,6 +195,31 @@ If not defined, the default rules for choosing a view will be followed.
 */
 #define kOfxImageEffectPropOCIOView "OfxImageEffectPropOCIOView"
 
+/** @brief
+
+ This action allows a host to ask an effect, given a list of preferred
+ colourspaces, what colourspace will be used for its output clip. This should
+ be called after first gathering the plug-ins preferred input colourspaces
+ via OfxImageEffectActionGetClipPreferences. The host must set
+ kOfxImageClipPropColourspace on the output clip to the chosen colourspace,
+ or the default value of OfxColourspace_Source.
+
+ @param  handle handle to the instance, cast to an \ref OfxImageEffectHandle
+ @param  inArgs has the property
+     - \ref kOfxImageClipPropPreferredColourspaces the list of preferred colourspaces
+
+ @param  outArgs has the property
+     - \ref kOfxImageClipPropColourspace the colourspace selected by the plug-in
+
+ @returns
+     -  \ref kOfxStatOK, the action was trapped and the colourspace was set in the outArgs property set
+     -  \ref kOfxStatReplyDefault, the action was not trapped and the host should use the default value of OfxColourspace_Source
+     -  \ref kOfxStatErrMemory, in which case the action may be called again after a memory purge
+     -  \ref kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message
+     -  \ref kOfxStatErrFatal
+ */
+#define kOfxImageEffectActionGetOutputColourspace "OfxImageEffectActionGetOutputColourspace"
+
 #ifdef __cplusplus
 }
 #endif

include/ofxImageEffect.h

@@ -307,6 +307,12 @@ These are the list of actions passed to an image effect plugin's main function.
      must be set to one of the pixel depths both the host and plugin
      supports
 
+     -  a set of char \* X 1 properties, one for each of the input clips
+     currently attached, labelled with
+     ``OfxImageClipPropPreferredColourspaces_`` post pended with the clip's
+     name. This must be set according to the requirements of the colour
+     management style in use.
+     
      -  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