Adsk Contrib - Implement display and view aliases

docs/guides/authoring/displays_views.rst

@@ -89,6 +89,11 @@ The keys allowed with a View are:
   and the '-' character to apply in reverse. See :ref:`config-looks`
 * ``rule``: The viewing rule to be used with this View. See :ref:`config-viewing-rules`
 * ``description``: A description string for this View.
+* ``aliases``: Alternative names that can be used to refer to this View. Unlike display
+  aliases, resolving a view by one of its aliases is always active (it does not depend
+  on ``use_display_aliases``). An alias must not collide with the name or an alias of
+  another view used by the same display (whether display-defined or a referenced
+  shared view). Requires ``ocio_profile_version`` 2.6 or higher.
 
 Note that a View may use either the colorspace key or it may use both
 the view_transform and dispay_colorspace keys.  No other combinations
@@ -132,6 +137,27 @@ A View Transform may use the following keys:
 
 .. TODO: Good spot for an example in a future revision.
 
+
+``use_display_aliases``
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Optional.  Activates aliases for display names.
+
+By default, the arguments to DisplayViewTransform must be the exact display name found
+in the display section of the config. However, if ``ocio_profile_version`` is 2.6 or
+higher, ``use_display_aliases`` may be set to true. This allows a display to be
+referred to by the name or aliases of its corresponding display ColorSpace. This
+config-level attribute defaults to false and must be omitted from the config file if
+its value is not "true".
+
+Note that this does not affect resolving a view by one of its ``aliases`` (see the View
+keys above), which is always active regardless of this setting.
+
+.. code-block:: yaml
+
+  use_display_aliases: true
+
+
 ``default_view_transform``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/releases/ocio_2_6.rst

@@ -15,6 +15,81 @@ calendar year 2027.
 New Feature Guide
 =================
 
+Display and View Aliases
+************************
+
+For Config Authors
+++++++++++++++++++
+
+Config authors may now define alias names for displays and views that will be recognized
+in a ``DisplayViewTransform`` as equivalent to the canonical names. Similar to color space
+aliases, this allows config authors to evolve naming of display and views over time while
+still providing backwards compatibility for the older names.
+
+Display aliasing is opt-in and the config author must set the new config-level attribute
+``use_display_aliases: true``. With that enabled, the name or aliases of the display color
+space for the display will be considered synonyms for that display. 
+
+View aliasing is allowed via a new ``aliases`` attribute on a view or shared view. These are
+always active, independent of whether ``use_display_aliases`` is enabled. Similar to other
+Yaml lists, these are separated by a comma. Names that contain an embedded comma are 
+enclosed in quotes to prevent it from being used as a separator.
+
+Please note that the ``active_displays`` and ``active_views`` lists must use the canonical names
+rather than aliases. Similarly, view aliases in a shared view may not be used when referring to
+the shared view in a display's views. 
+
+For virtual displays, aliases may be used with shared views but are 
+not suppored for display-defined virtual views.
+
+As an example, in the following config file excerpt, "srgb_rec709_display" could be used as
+a display alias and "aces2_sdr_view" could be used as a view alias when creating a
+``DisplayViewTransform``.
+
+.. code-block:: yaml
+
+    use_display_aliases: true
+
+    shared_views:
+      - !<View> {name: ACES 2.0 - SDR, view_transform: ACES 2.0 - SDR, 
+                 display_colorspace: <USE_DISPLAY_NAME>, aliases: [aces2_sdr_view]}
+
+    displays:
+      sRGB - Display:
+        - !<Views> [ACES 2.0 - SDR]
+
+    display_colorspaces:
+      - !<ColorSpace>
+        name: sRGB - Display
+        aliases: [srgb_rec709_display]
+
+For Developers
+++++++++++++++
+
+If application code is currently calling ``Config::getDisplayViewColorSpaceName``, you will
+probably want to change that to ``Config::getResolvedDisplayViewColorSpaceName`` so that it
+will handle aliases. Note that this resolves the ``<USE_DISPLAY_NAME>`` token, as well.
+
+Any existing calls to ``DisplayViewTransform`` should automatically work with aliases, without
+any changes.
+
+The new functions ``Config::getCanonicalDisplayName`` and ``Config::getCanonicalViewName`` may
+be used to convert aliases back to the primary name used in the config.
+
+
+Display Descriptions
+********************
+
+For Developers
+++++++++++++++
+
+On a related note, the new ``Config::getDisplayDescription`` allows applications to get a
+description for a display. This is sourced from the description attribute of the display
+color space that implements the display. (Views already have a description attribute
+available for config authors to set.) This enables applications to provide tool-tips or
+similar help text for both displays and views.
+
+
 New Fixed Function Transforms
 *****************************
 

include/OpenColorIO/OpenColorIO.h

@@ -656,10 +656,9 @@ class OCIOEXPORT Config
     void removeColorSpace(const char * name);
 
     /**
-     * Return true if the color space is used by a transform, a role, or a look.
-     *
-     * \note
-     *    Name must be the canonical name.
+     * Return true if the color space is used by a transform, a role, a look, a (display, view)
+     * pair, or a file rule. The argument may be either an alias or the canonical name. While
+     * searching the config, aliases are always resolved to their canonical names for comparison.
      */
     bool isColorSpaceUsed(const char * name) const noexcept;
 
@@ -863,6 +862,17 @@ class OCIOEXPORT Config
     void addSharedView(const char * view, const char * viewTransformName,
                        const char * colorSpaceName, const char * looks,
                        const char * ruleName, const char * description);
+    /**
+     * \brief As above, but also sets the view's aliases.
+     *
+     * Will throw if view or colorSpaceName are null or empty, or if an alias collides with the
+     * name or an alias of another shared view.
+     */
+    void addSharedView(const char * view, const char * viewTransformName,
+                       const char * colorSpaceName, const char * looks,
+                       const char * ruleName, const char * description,
+                       const std::vector<std::string> & aliases);
+
     /// Remove a shared view.  Will throw if the view does not exist.
     void removeSharedView(const char * view);
 
@@ -918,6 +928,8 @@ class OCIOEXPORT Config
     /**
      * Returns the colorspace attribute of the (display, view) pair.
      * (Note that this may be either a color space or a display color space.)
+     * See \ref Config::getResolvedDisplayViewColorSpaceName to first resolve
+     * any display or view aliases.
      */
     const char * getDisplayViewColorSpaceName(const char * display, const char * view) const;
     /// Returns the looks attribute of a (display, view) pair.
@@ -927,6 +939,28 @@ class OCIOEXPORT Config
     /// Returns the description attribute of a (display, view) pair.
     const char * getDisplayViewDescription(const char * display, const char * view) const noexcept;
 
+    /**
+     * \brief Get the number of aliases of a (display, view) pair. If display is null or
+     * empty, config shared views are used.
+     */
+    int getNumDisplayViewAliases(const char * display, const char * view) const noexcept;
+
+    /**
+     * \brief Get an alias of a (display, view) pair, by index. If display is null or empty,
+     * config shared views are used.
+     *
+     * Returns "" if the (display, view) pair does not exist or index is out of range.
+     */
+    const char * getDisplayViewAlias(const char * display, const char * view,
+                                     int index) const noexcept;
+
+    /**
+     * \brief Convenience method to check whether a (display, view) pair has a specific alias.
+     * If display is null or empty, config shared views are used.
+     */
+    bool hasDisplayViewAlias(const char * display, const char * view,
+                             const char * alias) const noexcept;
+
     /**
      * \brief Determine if a display and view exist.
      *
@@ -961,6 +995,20 @@ class OCIOEXPORT Config
                         const char * colorSpaceName, const char * looks,
                         const char * ruleName, const char * description);
 
+    /**
+     * \brief As above, but also sets the view's aliases.
+     *
+     * Will throw if:
+     * * Display, view or colorSpace are null or empty.
+     * * Display already has a shared view with the same name.
+     * * An alias collides with the name or an alias of another view in this display, whether
+     *   display-defined or a shared view referenced by this display.
+     */
+    void addDisplayView(const char * display, const char * view, const char * viewTransformName,
+                        const char * colorSpaceName, const char * looks,
+                        const char * ruleName, const char * description,
+                        const std::vector<std::string> & aliases);
+
     /**
      * \brief Add a (reference to a) shared view to a display.
      * 
@@ -985,6 +1033,83 @@ class OCIOEXPORT Config
     /// Clear all the displays.
     void clearDisplays();
 
+    /**
+     * Methods that involve resolving display and view aliases.
+     *
+     */
+
+    /**
+     * \brief This property on the Config object allows config authors to use aliases for
+     * display names. This feature is off by default.
+     *
+     * Corresponds to the "use_display_aliases" config file attribute, which is only
+     * written to the file when true. Requires config version 2.6 or higher (validation
+     * will fail if this is enabled on an older config).
+     */
+    bool getUseDisplayAliases() const noexcept;
+    void setUseDisplayAliases(bool enabled) noexcept;
+
+    /**
+     * \brief Resolve display name aliases.
+     *
+     * If the argument does not match an existing display, a fallback checks if getColorSpace
+     * returns a display color space. If so, it checks to see if there is a display whose
+     * name matches that color space name or one of its aliases.
+     *
+     * This fallback is only performed if \ref Config::getUseDisplayAliases is true.
+     *
+     * Returns "" if no display can be found, even with the fallback.
+     */
+    const char * getCanonicalDisplayName(const char * displayName) const;
+
+    /**
+     * \brief Resolve view name aliases.
+     *
+     * If the arguments do not directly match an existing (display, view) pair, this looks for
+     * a view used by the display (whether display-defined or a referenced shared view, active
+     * or inactive) that has viewName as one of its aliases (see \ref Config::addDisplayView
+     * and \ref Config::addSharedView).
+     *
+     * The displayName is first resolved via \ref Config::getCanonicalDisplayName.
+     *
+     * Returns "" if no display and view can be found, even with the fallback, or if the
+     * arguments are null or empty.
+     */
+    const char * getCanonicalViewName(const char * displayName, const char * viewName) const;
+
+    /**
+     * \brief Returns the name of the color space that a (display, view) pair uses.
+     *
+     * This is similar to \ref Config::getDisplayViewColorSpaceName, but it first attempts
+     * to resolve displayName and viewName (which could be aliases) to their canonical names,
+     * via \ref Config::getCanonicalDisplayName and \ref Config::getCanonicalViewName. And
+     * unlike that function, the displayName may not be empty.
+     *
+     * In addition, if the display_colorspace of a shared view is <USE_DISPLAY_NAME>, that
+     * is resolved to the name of the view's display.
+     *
+     * Note that, as with getDisplayViewColorSpaceName, the returned name may be that of a
+     * named transform rather than a color space (this is allowed for views that have no
+     * view_transform).
+     *
+     * Returns either the canonical name of the view's color space or, if that does not
+     * find a result, the raw color space string (which would likely be used in an error
+     * message). If the (display, view) pair cannot even be resolved, it returns "".
+     */
+    const char * getResolvedDisplayViewColorSpaceName(const char * displayName,
+                                                      const char * viewName) const;
+
+    /**
+     * \brief Return the description of the display color space associated with displayName.
+     *
+     * If displayName matches the canonical name of a display color space, its description is
+     * returned. If \ref Config::getUseDisplayAliases is true, the search is broadened to
+     * include display color spaces that have displayName as an alias.
+     *
+     * Returns "" if no such display color space can be found.
+     */
+    const char * getDisplayDescription(const char * displayName) const;
+
     /**
      * Methods related to the Virtual Display.
      *
@@ -1114,6 +1239,9 @@ class OCIOEXPORT Config
      * the config file as well as any modifications made by the client app. These functions
      * only get and set what is in the config object and do not take into account the override
      * and thus may not represent the actual user experience.
+     *
+     * Display aliases may not be used in the active list, use \ref Config::getCanonicalDisplayName
+     * to convert any aliases to their canonical name.
      */
     /// Set all active displays at once as a comma or colon delimited string. This replaces any
     /// previous contents of the list.
@@ -1152,6 +1280,9 @@ class OCIOEXPORT Config
      * the config file as well as any modifications made by the client app. These functions
      * only get and set what is in the config object and do not take into account the override
      * and thus may not represent the actual user experience.
+     *
+     * View aliases may not be used in the active list, use \ref Config::getCanonicalViewName
+     * to convert any aliases to their canonical name.
      */
     /// Set all active views at once as a comma or colon delimited string. This replaces any
     /// previous contents of the list.
@@ -2555,6 +2686,7 @@ class OCIOEXPORT ViewTransform
     ViewTransformRcPtr createEditableCopy() const;
 
     const char * getName() const noexcept;
+    /// \see ColorSpace::setName
     void setName(const char * name) noexcept;
 
     /// \see ColorSpace::getFamily
@@ -2563,6 +2695,7 @@ class OCIOEXPORT ViewTransform
     void setFamily(const char * family);
 
     const char * getDescription() const noexcept;
+    /// \see ColorSpace::setDescription
     void setDescription(const char * description);
 
     /**