Adsk Contrib - Implement config compatibility validation for HDR displays

docs/api/apphelpers.rst

@@ -46,6 +46,65 @@ ColorSpaceMenuHelpers
       .. doxygentypedef:: ${OCIO_NAMESPACE}::ConstColorSpaceMenuHelperRcPtr
       .. doxygentypedef:: ${OCIO_NAMESPACE}::ColorSpaceMenuHelperRcPtr
 
+ConfigCompatibilityHelpers
+**************************
+
+.. tabs::
+
+   .. group-tab:: Python
+
+      .. autofunction:: PyOpenColorIO.ConfigCompatibilityHelpers.CheckCompatibility
+
+   .. group-tab:: C++
+
+      .. doxygennamespace:: ${OCIO_NAMESPACE}::ConfigCompatibilityHelpers
+         :members:
+         :undoc-members:
+
+ConfigMergingHelpers
+********************
+
+.. tabs::
+
+   .. group-tab:: Python
+
+      .. autofunction:: PyOpenColorIO.ConfigMergingHelpers.MergeConfigs
+      .. autofunction:: PyOpenColorIO.ConfigMergingHelpers.MergeColorSpace
+
+      .. autoclass:: PyOpenColorIO.ConfigMergingParameters
+         :members:
+         :undoc-members:
+         :special-members: __init__, __str__
+         :exclude-members: MergeStrategies
+
+      .. autoclass:: PyOpenColorIO.ConfigMergingParameters.MergeStrategies
+         :members:
+         :undoc-members:
+         :exclude-members: name
+
+      .. autoclass:: PyOpenColorIO.ConfigMerger
+         :members:
+         :undoc-members:
+         :special-members: __init__, __str__
+
+   .. group-tab:: C++
+
+      .. doxygenclass:: ${OCIO_NAMESPACE}::ConfigMergingParameters
+         :members:
+         :undoc-members:
+
+      .. doxygenfunction:: ${OCIO_NAMESPACE}::operator<<(std::ostream&, const ConfigMergingParameters&)
+
+      .. doxygenclass:: ${OCIO_NAMESPACE}::ConfigMerger
+         :members:
+         :undoc-members:
+
+      .. doxygenfunction:: ${OCIO_NAMESPACE}::operator<<(std::ostream&, const ConfigMerger&)
+
+      .. doxygennamespace:: ${OCIO_NAMESPACE}::ConfigMergingHelpers
+         :members:
+         :undoc-members:
+
 DisplayViewHelpers
 ******************
 

docs/api/enums.rst

@@ -482,3 +482,19 @@ ProcessorCacheFlags
    .. group-tab:: C++
 
       .. doxygenenum:: ${OCIO_NAMESPACE}::ProcessorCacheFlags
+
+ConfigCompatibility
+********************
+
+.. tabs::
+
+   .. group-tab:: Python
+
+      .. autoclass:: PyOpenColorIO.ConfigCompatibility
+         :members:
+         :undoc-members:
+         :exclude-members: name
+
+   .. group-tab:: C++
+
+      .. doxygenenum:: ${OCIO_NAMESPACE}::ConfigCompatibility

include/OpenColorIO/OpenColorAppHelpers.h

@@ -275,6 +275,19 @@ class OCIOEXPORT ColorSpaceMenuHelper
 
 extern OCIOEXPORT std::ostream & operator<<(std::ostream &, const ColorSpaceMenuHelper &);
 
+namespace ConfigCompatibilityHelpers
+{
+/**
+ * \brief Check the config for compatibility with a specific requirement.
+ *
+ * Returns false if the config is not compatible with the requirement identified by the given
+ * ConfigCompatibility value.
+ */
+extern OCIOEXPORT bool CheckCompatibility(const ConstConfigRcPtr & config,
+                                          ConfigCompatibility compatibility);
+
+} // namespace ConfigCompatibilityHelpers
+
 namespace ColorSpaceHelpers
 {
 /**

include/OpenColorIO/OpenColorTypes.h

@@ -743,6 +743,13 @@ enum ProcessorCacheFlags : unsigned int
     PROCESSOR_CACHE_DEFAULT = (PROCESSOR_CACHE_ENABLED | PROCESSOR_CACHE_SHARE_DYN_PROPERTIES)
 };
 
+//!cpp:type:: Enum identifying a specific compatibility requirement that a Config may be checked
+// against via :cpp:func:`ConfigCompatibilityHelpers::CheckCompatibility`.
+enum ConfigCompatibility
+{
+    CONFIG_HDR_DISPLAY_SUPPORT_26 = 0   // Config meets HDR display compatibility reqmts as of OCIO 2.6.
+};
+
 // Conversion
 
 extern OCIOEXPORT const char * BoolToString(bool val);

src/OpenColorIO/CMakeLists.txt

@@ -4,6 +4,7 @@
 set(SOURCES
     apphelpers/CategoryHelpers.cpp
     apphelpers/ColorSpaceHelpers.cpp
+    apphelpers/ConfigCompatibility.cpp
     apphelpers/DisplayViewHelpers.cpp
     apphelpers/LegacyViewingPipeline.cpp
     apphelpers/mergeconfigs/MergeConfigsHelpers.cpp

src/OpenColorIO/apphelpers/ConfigCompatibility.cpp

@@ -0,0 +1,223 @@
+// SPDX-License-Identifier: BSD-3-Clause
+// Copyright Contributors to the OpenColorIO Project.
+
+
+#include <string>
+
+#include <OpenColorIO/OpenColorIO.h>
+
+#include "ConfigCompatibility.h"
+#include "Logging.h"
+
+
+namespace OCIO_NAMESPACE
+{
+
+namespace ConfigCompatibilityHelpers
+{
+
+bool DisplayColorSpacesHaveAttributes(const ConstConfigRcPtr & config)
+{
+    // Search all (active & inactive) display color spaces.
+
+    const int numCS = config->getNumColorSpaces(SEARCH_REFERENCE_SPACE_DISPLAY, COLORSPACE_ALL);
+    if (numCS == 0)
+    {
+        LogDebug("HDR Display Support (2.6): No display-referred color spaces found.");
+        return false;
+    }
+
+    bool allHaveInteropID = true;
+
+    for (int i = 0; i < numCS; ++i)
+    {
+        const char * csName = config->getColorSpaceNameByIndex(SEARCH_REFERENCE_SPACE_DISPLAY,
+                                                               COLORSPACE_ALL, i);
+        ConstColorSpaceRcPtr cs = config->getColorSpace(csName);
+
+        // Having the interop ID allows applications to match up a display color space with
+        // external color space definitions, such as operating system color space enums.
+
+        if (!cs || !cs->getInteropID() || !*cs->getInteropID())
+        {
+            LogDebug(std::string("HDR Display Support (2.6): Display color space '") + csName +
+                     "' has no interop ID.");
+            allHaveInteropID = false;
+        }
+
+        // The encoding attribute allows applications to know whether this color space is
+        // for an SDR or HDR monitor and whether it is a linear or gamma-corrected encoding.
+
+        if (!cs || !cs->getEncoding() || !*cs->getEncoding())
+        {
+            LogDebug(std::string("HDR Display Support (2.6): Display color space '") + csName +
+                     "' has no encoding.");
+            allHaveInteropID = false;
+        }
+    }
+
+    return allHaveInteropID;
+}
+
+bool ActiveDisplaysHaveColorSpace(const ConstConfigRcPtr & config)
+{
+    // Only check active displays.
+    const int numDisplays = config->getNumDisplays();
+    if (numDisplays == 0)
+    {
+        LogDebug("HDR Display Support (2.6): No active displays.");
+        return false;
+    }
+
+    bool allHaveColorSpace = true;
+
+    // Having a display color space for each display allows applications to convert the
+    // output from a DisplayViewTransform back to the display-referred reference space
+    // and from there to any color space that may be required by the operating system.
+
+    for (int d = 0; d < numDisplays; ++d)
+    {
+        const char * display = config->getDisplay(d);
+        ConstColorSpaceRcPtr cs = config->getColorSpace(display);
+        if (!cs || cs->getReferenceSpaceType() != REFERENCE_SPACE_DISPLAY)
+        {
+            LogDebug(std::string("HDR Display Support (2.6): Display '") + display +
+                     "' has no matching display-referred color space.");
+            allHaveColorSpace = false;
+        }
+    }
+
+    return allHaveColorSpace;
+}
+
+bool ActiveViewsHaveViewTransform(const ConstConfigRcPtr & config)
+{
+    // Only check active displays.
+    const int numDisplays = config->getNumDisplays();
+
+    int numViewsTotal = 0;
+    bool allHaveViewTransform = true;
+    bool hasViewTransform = false;
+
+    for (int d = 0; d < numDisplays; ++d)
+    {
+        const char * display = config->getDisplay(d);
+        // Only check active views.
+        const int numViews = config->getNumViews(display);
+        for (int v = 0; v < numViews; ++v)
+        {
+            ++numViewsTotal;
+
+            // Being structured as a ViewTransform plus a display color space is the
+            // best-practice for configs and structures the processing to give the
+            // application the most flexibility to conform to the OS requirements.
+
+            const char * view = config->getView(display, v);
+            const char * transformName = config->getDisplayViewTransformName(display, view);
+            if (transformName && *transformName)
+            {
+                hasViewTransform = true;
+                continue;
+            }
+
+            // However, sometimes a config will include a few "utility" views, such as a
+            // "Raw" view, implemented as a color space where isData is true, and this
+            // should not disqualify a config.
+
+            const char * csName = config->getDisplayViewColorSpaceName(display, view);
+            ConstColorSpaceRcPtr cs = csName && *csName ? config->getColorSpace(csName) :
+                                                          ConstColorSpaceRcPtr();
+            if (cs && cs->isData())
+            {
+                continue;
+            }
+
+            // Similarly, configs sometimes will structure "utility" views using a
+            // NamedTransform as the color space. End-user expectations for such views
+            // is not that they will provide exact colorimetry. As long as the application
+            // has a display color space for the view, that should be sufficient context
+            // for how to handle the resulting output.
+
+            ConstNamedTransformRcPtr nt = csName && *csName ? config->getNamedTransform(csName) :
+                                                              ConstNamedTransformRcPtr();
+            if (nt)
+            {
+                continue;
+            }
+
+            LogDebug(std::string("HDR Display Support (2.6): Active (display, view) pair ('") + display +
+                     "', '" + view + "') has no view transform and is not a data color space "
+                     "or a named transform.");
+            allHaveViewTransform = false;
+        }
+    }
+
+    if (numViewsTotal == 0)
+    {
+        LogDebug("HDR Display Support (2.6): No active (display, view) pairs.");
+        return false;
+    }
+
+    if (!hasViewTransform)
+    {
+        LogDebug("HDR Display Support (2.6): No active (display, view) pair references a view "
+                 "transform.");
+    }
+
+    return allHaveViewTransform && hasViewTransform;
+}
+
+bool CheckHDRDisplaySupport26(const ConstConfigRcPtr & config)
+{
+    bool compatible = true;
+
+    // Ideally, an application will be able to use the interop IDs in the display color
+    // spaces to identify one that corresponds to the color space required by the OS.
+    // An OCIO ColorSpaceTransform may then be used to convert from the display color
+    // space produced by the DisplayViewTransform into the required OS color space.
+    //
+    // However, if that is not available, the display-referred interchange role is a key
+    // piece of information for applications, allowing them to invert the display color
+    // spaces back to CIE XYZ D65 and then convert forward to whatever color space is
+    // required. For example, the interchange role facilitates using GetProcessorFromConfigs
+    // to convert from a display color space in a user's config to a display color space
+    // in one of the built-in configs.
+
+    if (!config->hasRole(ROLE_INTERCHANGE_DISPLAY))
+    {
+        LogDebug("HDR Display Support (2.6): Missing the 'cie_xyz_d65_interchange' role.");
+        compatible = false;
+    }
+
+    if (!DisplayColorSpacesHaveAttributes(config))
+    {
+        compatible = false;
+    }
+
+    if (!ActiveDisplaysHaveColorSpace(config))
+    {
+        compatible = false;
+    }
+
+    if (!ActiveViewsHaveViewTransform(config))
+    {
+        compatible = false;
+    }
+
+    return compatible;
+}
+
+bool CheckCompatibility(const ConstConfigRcPtr & config, ConfigCompatibility compatibility)
+{
+    switch (compatibility)
+    {
+    case CONFIG_HDR_DISPLAY_SUPPORT_26:
+        return CheckHDRDisplaySupport26(config);
+    }
+
+    return false;
+}
+
+} // namespace ConfigCompatibilityHelpers
+
+} // namespace OCIO_NAMESPACE

src/OpenColorIO/apphelpers/ConfigCompatibility.h

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: BSD-3-Clause
+// Copyright Contributors to the OpenColorIO Project.
+
+
+#ifndef INCLUDED_OCIO_CONFIG_COMPATIBILITY_H
+#define INCLUDED_OCIO_CONFIG_COMPATIBILITY_H
+
+#include <OpenColorIO/OpenColorIO.h>
+
+
+namespace OCIO_NAMESPACE
+{
+
+namespace ConfigCompatibilityHelpers
+{
+
+// Returns true if the config has at least one display color space (active or inactive) and all
+// of them have an interop ID and an encoding set.
+bool DisplayColorSpacesHaveAttributes(const ConstConfigRcPtr & config);
+
+// Returns true if the config has at least one active display and each active display has a
+// display-referred color space matching its name.
+bool ActiveDisplaysHaveColorSpace(const ConstConfigRcPtr & config);
+
+// Returns true if the config has at least one active (display, view) pair using a view transform,
+// and all views reference a non-empty view transform, except that a view with no view transform is
+// allowed if the color space it refers to has isData set to true or if it refers to a named
+// transform.
+bool ActiveViewsHaveViewTransform(const ConstConfigRcPtr & config);
+
+// Check HDR display compatibility requirements, as of OCIO 2.6.
+bool CheckHDRDisplaySupport26(const ConstConfigRcPtr & config);
+
+} // namespace ConfigCompatibilityHelpers
+
+} // namespace OCIO_NAMESPACE
+
+#endif // INCLUDED_OCIO_CONFIG_COMPATIBILITY_H