Reworked the OCIO extension to support ACES

The OCIO API has been extended to be a broader colour management API, although still using OCIO as the foundation.

This commit adds the ACESCG and ACES colour management styles, which only use OCIO as a source of colourspace names and could be implemented using other colour management pipelines.

OCIO-specific properties are separated and form a superset of the functionality offered by the ACES styles.

Signed-off-by: John-Paul Smith <[email protected]>

include/ofxImageEffect.h

@@ -1048,106 +1048,144 @@ This property acts as a hint to hosts indicating that they could feed the effect
 */
 #define kOfxImageClipPropIsMask "OfxImageClipPropIsMask"
 
-/** @brief Does a host or plug-in support OCIO?
+/** @brief What style of colour management does the host or plug-in offer?
 
-   - Type - int X 1
+   - Type - string X 1
    - Property Set - host descriptor (read only), plugin descriptor (read/write)
-   - Default - 0
-   - Valid Values - This must be one of 0 or 1
+   - Default - kOfxImageEffectPropColourManagementStyleNone
+   - Valid Values - This must be one of
+     - ::kOfxImageEffectPropColourManagementNone - no colour management
+     - ::kOfxImageEffectPropColourManagementACESCG - colourspaces from the OCIO built-in ACES CG config are available
+     - ::kOfxImageEffectPropColourManagementACES - colourspaces from the OCIO built-in ACES Studio config are available
+     - ::kOfxImageEffectPropColourManagementOCIO - any OCIO config may be used (implies use of the OCIO library)
 
-Hosts should set this property if they will provide OCIO configuration 
-information to plug-ins.
-Plug-ins should set this property if they can use host-provided OCIO 
-configuration. A host might not natively use OCIO but could provide a 
-compatibility config purely the purposes of communicating colour information 
-to plug-ins. As this may incur a cost for the host, plug-ins should only 
-set this property to 1 if they will actually benefit from colour information.
+Hosts should set this property if they will provide colourspace information 
+to plug-ins.
+Plug-ins should set this property if they can use host-provided colourspace 
+information. OCIO is used as the reference for the colour management API, but 
+is not required to implement the ACESCG or ACES styles.
+
+The colourspace strings used in the ACESCG style are from:
+https://github.com/AcademySoftwareFoundation/OpenColorIO-Config-ACES/releases/download/v1.0.0/cg-config-v1.0.0_aces-v1.3_ocio-v2.1.ocio
+
+The colourspace strings used in the ACES style are from:
+https://github.com/AcademySoftwareFoundation/OpenColorIO-Config-ACES/releases/download/v1.0.0/studio-config-v1.0.0_aces-v1.3_ocio-v2.1.ocio
+
+The assumption is that OCIO > ACES > ACESCG so the highest style supported by 
+both host and plug-in will be chosen.
 */
-#define kOfxImageEffectPropSupportsOCIO "OfxImageEffectPropSupportsOCIO"
+#define kOfxImageEffectPropColourManagementStyle "OfxImageEffectPropColourManagementStyle"
+
+/* String used to indicate that no colour management is available. */
+#define kOfxImageEffectPropColourManagementNone "OfxImageEffectPropColourManagementNone"
+/* String used to indicate that basic colour management is available. */
+#define kOfxImageEffectPropColourManagementACESCG "OfxImageEffectPropColourManagementACESCG"
+/* String used to indicate that ACES colour management is available. */
+#define kOfxImageEffectPropColourManagementACES "OfxImageEffectPropColourManagementACES"
+/* String used to indicate that OCIO colour management is available. */
+#define kOfxImageEffectPropColourManagementOCIO "OfxImageEffectPropColourManagementOCIO"
 
 /** @brief The path to the OCIO config used for this instance
 
    - Type - string X 1
    - Property Set - image effect instance (read only)
-   - Valid Values - Filesystem path to the config
+   - Valid Values - Filesystem path to the config or URI starting ocio://
 
-Hosts should set this property on any effect instances which it would like to colour manage using OCIO.
+A host must set this property on any effect instances where it has negotiated 
+OCIO colour management (kOfxImageEffectPropColourManagementOCIO).
+Use of URIs for built-in configs, such as ocio://default is permitted.
 */
 #define kOfxImageEffectPropOCIOConfig "OfxImageEffectPropOCIOConfig"
 
-/** @brief The OCIO colourspace used for this clip
+/** @brief The colourspace used for this clip
 
    - Type - string X 1
    - Property Set - clip instance (read/write)
-   - Valid Values - colourspace that is present in the config
+   - Valid Values - colourspace that is permitted under the style in use
 
 Hosts should set this property to the colourspace of the input clip. Typically 
 it will be set to the working colourspace of the host but could be any valid 
-colourspace from the config.
-Plug-ins may set this property on an output clip to a valid colourspace from 
-the host-supplied config.
+colourspace.
+Plug-ins may set this property on an output clip. Plug-ins which output motion 
+vectors or similar images which should not be colour managed can use the data 
+colourspace which is present in the built-in OCIO configs.
 Both host and plug-in should use the value of 
-kOfxImageClipPropOCIOPreferredColourspace where reasonable.
+kOfxImageClipPropPreferredColourspace where reasonable.
 */
-#define kOfxImageClipPropOCIOColourspace "OfxImageClipPropOCIOColourspace"
+#define kOfxImageClipPropColourspace "OfxImageClipPropColourspace"
 
-/** @brief The preferred OCIO colourspace used for this clip
+/** @brief The preferred colourspace for this clip
 
    - Type - string X 1
    - Property Set - clip instance (read only) and ::kOfxImageEffectActionGetClipPreferences action out args property (read/write)
-   - Valid Values - colourspace that is present in the config
+   - Valid Values - colourspace that is permitted under the style in use. 
+                    For ACESCG and ACES, this a any colourspace from the colorspaces or roles section of the relevant config.
+                    For OCIO, this could be any string acceptable to Config::getColorSpace().
 
 Plug-ins may set this property during kOfxImageEffectActionGetClipPreferences 
 to request the image in a certain colourspace. Hosts may optionally provide 
 input images in this colourspace, but must always set 
-kOfxImageClipPropOCIOColourspace to the actual colourspace used.
+kOfxImageClipPropColourspace to the actual colourspace used.
 Hosts may set this on an output clip, which could be helpful in a generator 
 context.
+
+It might be much less costly for a host to perform a conversion 
+than a plug-in, so in the example of a plug-in which performs all internal 
+processing in scene linear, it is sensible for the plug-in to universally 
+assert that preference and the host to honour it if possible. However, if a 
+plug-in is capable of adapting to any input colourspace, it should not set 
+this preference.
+*/
+#define kOfxImageClipPropPreferredColourspace "OfxImageClipPropPreferredColourspace"
+
+/** @brief The display colourspace used in the plug-in's viewport
+
+   - Type - string X 1
+   - Property Set - image effect instance (read only)
+   - Valid Values - colourspace from the display_colorspaces section of the relevant ACES OCIO config
+
+Used with the ACESCG or ACES colour management styles, this property is relevant 
+for plug-ins which have their own viewport in a custom window. Plug-ins should 
+not expect this to be available during a render event.
+Hosts should set this property to a display colourspace which matches that 
+used in its own viewport. For a multi-display system, choose the colourspace 
+for the display device where a native window would appear by default.
+A host which supports OCIO should use the OCIO-specific display, view and look 
+properties instead.
+ 
 */
-#define kOfxImageClipPropOCIOPreferredColourspace "OfxImageClipPropOCIOPreferredColourspace"
+#define kOfxImageEffectPropDisplayColourspace "OfxImageEffectPropDisplayColourspace"
 
-/** @brief The OCIO display used in the plug-in's viewport
+/** @brief The OCIO display to be used in the plug-in's viewport
 
    - Type - string X 1
    - Property Set - image effect instance (read only)
    - Valid Values - OCIO display that is present in the config
 
-This property is relevant for plug-ins which have their own viewport in a 
-custom window. Plug-ins should not expect this to be available during a render 
-event.
-Hosts should set this property to a display from the config which the plug-in 
-should use for any image display in its own viewport. For a host which uses 
-OCIO natively, this would typically match the display used in its own viewport. 
+This OCIO-specific property allows the host to specify which OCIO display should be used. 
+If not defined, the default rules for choosing a display will be followed.
 */
 #define kOfxImageEffectPropOCIODisplay "OfxImageEffectPropOCIODisplay"
 
-/** @brief The OCIO display view used in the plug-in's viewport
+/** @brief The OCIO view to be used in the plug-in's viewport
 
    - Type - string X 1
    - Property Set - image effect instance (read only)
-   - Valid Values - OCIO view that is present in the config
-
-This property is relevant for plug-ins which have their own viewport in a 
-custom window. Plug-ins should not expect this to be available during a render 
-event.
-Hosts should set this property to a view from the config which the plug-in 
-should use for any image display in its own viewport. For a host which uses 
-OCIO natively, this would typically match the view used in its own viewport. 
+   - Valid Values - OCIO view for the display specified by kOfxImageEffectPropOCIODisplay
+
+This OCIO-specific property allows the host to specify which OCIO view should be used.
+If not defined, the default rules for choosing a view will be followed.
 */
-#define kOfxImageEffectPropOCIODisplayView "OfxImageEffectPropOCIODisplayView"
+#define kOfxImageEffectPropOCIOView "OfxImageEffectPropOCIOView"
 
 /** @brief The OCIO look used in the plug-in's viewport
 
    - Type - string X 1
    - Property Set - image effect instance (read only)
    - Valid Values - OCIO look that is present in the config
 
-This property is relevant for plug-ins which have their own viewport in a 
-custom window. Plug-ins should not expect this to be available during a render 
-event.
-Hosts should set this property to a look from the config which the plug-in 
-should use for any image display in its own viewport. For a host which uses 
-OCIO natively, this would typically match the look used in its own viewport.
+This OCIO-specific property allows the host to specify which OCIO look should be used.
+If not defined, no look will be applied.
 */
 #define kOfxImageEffectPropOCIOLook "OfxImageEffectPropOCIOLook"