wayland: Update the color management protocol

No functional changes, just minor updates to track the latest upstream version.

src/video/wayland/SDL_waylandcolor.c

@@ -236,9 +236,9 @@ static void image_description_handle_failed(void *data,
     }
 }
 
-static void image_description_handle_ready(void *data,
-                                           struct wp_image_description_v1 *wp_image_description_v1,
-                                           uint32_t identity)
+static void image_description_handle_ready2(void *data,
+                                            struct wp_image_description_v1 *wp_image_description_v1,
+                                            uint32_t identity_hi, uint32_t identity_lo)
 {
     Wayland_ColorInfoState *state = (Wayland_ColorInfoState *)data;
 
@@ -263,9 +263,17 @@ static void image_description_handle_ready(void *data,
     }
 }
 
+static void image_description_handle_ready(void *data,
+                                           struct wp_image_description_v1 *wp_image_description_v1,
+                                           uint32_t identity)
+{
+    image_description_handle_ready2(data, wp_image_description_v1, 0, identity);
+}
+
 static const struct wp_image_description_v1_listener image_description_listener = {
     image_description_handle_failed,
-    image_description_handle_ready
+    image_description_handle_ready,
+    image_description_handle_ready2
 };
 
 void Wayland_GetColorInfoForWindow(SDL_WindowData *window_data, bool defer_event_processing)

src/video/wayland/SDL_waylandvideo.c

@@ -1331,7 +1331,7 @@ static void handle_registry_global(void *data, struct wl_registry *registry, uin
     } else if (SDL_strcmp(interface, "frog_color_management_factory_v1") == 0) {
         d->frog_color_management_factory_v1 = wl_registry_bind(d->registry, id, &frog_color_management_factory_v1_interface, 1);
     } else if (SDL_strcmp(interface, "wp_color_manager_v1") == 0) {
-        d->wp_color_manager_v1 = wl_registry_bind(d->registry, id, &wp_color_manager_v1_interface, 1);
+        d->wp_color_manager_v1 = wl_registry_bind(d->registry, id, &wp_color_manager_v1_interface, SDL_min(version, 2));
         Wayland_InitColorManager(d);
     } else if (SDL_strcmp(interface, "wp_pointer_warp_v1") == 0) {
         d->wp_pointer_warp_v1 = wl_registry_bind(d->registry, id, &wp_pointer_warp_v1_interface, 1);

src/video/wayland/SDL_waylandwindow.c

@@ -1706,16 +1706,25 @@ static const struct frog_color_managed_surface_listener frog_surface_listener =
     frog_preferred_metadata_handler
 };
 
+
+static void handle_surface_feedback_preferred_changed2(void *data,
+                                                       struct wp_color_management_surface_feedback_v1 *wp_color_management_surface_feedback_v1,
+                                                       uint32_t identity_hi, uint32_t identity_lo)
+{
+    SDL_WindowData *wind = (SDL_WindowData *)data;
+    Wayland_GetColorInfoForWindow(wind, false);
+}
+
 static void handle_surface_feedback_preferred_changed(void *data,
                                                       struct wp_color_management_surface_feedback_v1 *wp_color_management_surface_feedback_v1,
                                                       uint32_t identity)
 {
-    SDL_WindowData *wind = (SDL_WindowData *)data;
-    Wayland_GetColorInfoForWindow(wind, false);
+    handle_surface_feedback_preferred_changed2(data, wp_color_management_surface_feedback_v1, 0, identity);
 }
 
 static const struct wp_color_management_surface_feedback_v1_listener color_management_surface_feedback_listener = {
-    handle_surface_feedback_preferred_changed
+    handle_surface_feedback_preferred_changed,
+    handle_surface_feedback_preferred_changed2
 };
 
 static void Wayland_SetKeyboardFocus(SDL_Window *window, bool set_focus)

wayland-protocols/color-management-v1.xml

@@ -31,9 +31,14 @@
   <description summary="color management protocol">
     The aim of the color management extension is to allow clients to know
     the color properties of outputs, and to tell the compositor about the color
-    properties of their content on surfaces. Doing this enables a compositor
-    to perform automatic color management of content for different outputs
-    according to how content is intended to look like.
+    properties of their content on surfaces. All surface contents must be
+    readily intended for some display, but not necessarily for the display at
+    hand. Doing this enables a compositor to perform automatic color management
+    of content for different outputs according to how content is intended to
+    look like.
+
+    For an introduction, see the section "Color management" in the Wayland
+    documentation at https://wayland.freedesktop.org/docs/html/ .
 
     The color properties are represented as an image description object which
     is immutable after it has been created. A wl_output always has an
@@ -43,16 +48,17 @@
     description on a wl_surface to denote the color characteristics of the
     surface contents.
 
-    An image description includes SDR and HDR colorimetry and encoding, HDR
-    metadata, and viewing environment parameters. An image description does
-    not include the properties set through color-representation extension.
-    It is expected that the color-representation extension is used in
-    conjunction with the color management extension when necessary,
-    particularly with the YUV family of pixel formats.
+    An image description essentially defines a display and (indirectly) its
+    viewing environment. An image description includes SDR and HDR colorimetry
+    and encoding, HDR metadata, and some parameters related to the viewing
+    environment. An image description does not include the properties set
+    through color-representation extension. It is expected that the
+    color-representation extension is used in conjunction with the
+    color-management extension when necessary, particularly with the YUV family
+    of pixel formats.
 
-    Recommendation ITU-T H.273
-    "Coding-independent code points for video signal type identification"
-    shall be referred to as simply H.273 here.
+    The normative appendix for this protocol is in the appendix.md file beside
+    this XML file.
 
     The color-and-hdr repository
     (https://gitlab.freedesktop.org/pq/color-and-hdr) contains
@@ -71,7 +77,7 @@
     only be done by creating a new major version of the extension.
   </description>
 
-  <interface name="wp_color_manager_v1" version="1">
+  <interface name="wp_color_manager_v1" version="2">
     <description summary="color manager singleton">
       A singleton global interface used for getting color management extensions
       for wl_surface and wl_output objects, and for creating client defined
@@ -118,6 +124,14 @@
              summary="ICC-absolute colorimetric"/>
       <entry name="relative_bpc" value="4"
              summary="media-relative colorimetric + black point compensation"/>
+      <entry name="absolute_no_adaptation" value="5" since="2">
+        <description summary="ICC-absolute colorimetric without adaptation">
+          This rendering intent is a modified absolute rendering intent that
+          assumes the viewer is not adapted to the display white point, so no
+          chromatic adaptation between surface and display is done.
+          This can be useful for color proofing applications.
+        </description>
+      </entry>
     </enum>
 
     <enum name="feature">
@@ -149,18 +163,14 @@
         </description>
       </entry>
       <entry name="windows_scrgb" value="7"
-             summary="get_windows_scrgb request"/>
+             summary="create_windows_scrgb request"/>
     </enum>
 
     <enum name="primaries">
       <description summary="named color primaries">
-        Named color primaries used to encode well-known sets of primaries. H.273
-        is the authority, when it comes to the exact values of primaries and
-        authoritative specifications, where an equivalent code point exists.
+        Named color primaries used to encode well-known sets of primaries.
 
         A value of 0 is invalid and will never be present in the list of enums.
-
-        Descriptions do list the specifications for convenience.
       </description>
 
       <entry name="srgb" value="1">
@@ -173,7 +183,6 @@
           - IEC 61966-2-4
           - Society of Motion Picture and Television Engineers (SMPTE) RP 177
             (1993) Annex B
-          Equivalent to H.273 ColourPrimaries code point 1.
         </description>
       </entry>
       <entry name="pal_m" value="2">
@@ -184,7 +193,6 @@
             Recommendation for transmission standards for color television
           - United States Federal Communications Commission (2003) Title 47 Code
             of Federal Regulations 73.682 (a)(20)
-          Equivalent to H.273 ColourPrimaries code point 4.
         </description>
       </entry>
       <entry name="pal" value="3">
@@ -194,7 +202,6 @@
           - Rec. ITU-R BT.601-7 625
           - Rec. ITU-R BT.1358-0 625 (historical)
           - Rec. ITU-R BT.1700-0 625 PAL and 625 SECAM
-          Equivalent to H.273 ColourPrimaries code point 5.
         </description>
       </entry>
       <entry name="ntsc" value="4">
@@ -205,13 +212,13 @@
           - Rec. ITU-R BT.1700-0 NTSC
           - SMPTE 170M (2004)
           - SMPTE 240M (1999) (historical)
-          Equivalent to H.273 ColourPrimaries code point 6 and 7.
         </description>
       </entry>
       <entry name="generic_film" value="5">
         <description summary="Generic film with colour filters using Illuminant C">
-          Color primaries as defined by H.273 for generic film.
-          Equivalent to H.273 ColourPrimaries code point 8.
+          Color primaries as defined by Recommendation ITU-T H.273
+          "Coding-independent code points for video signal type identification"
+          for "generic film".
         </description>
       </entry>
       <entry name="bt2020" value="6">
@@ -219,7 +226,6 @@
           Color primaries as defined by
           - Rec. ITU-R BT.2020-2
           - Rec. ITU-R BT.2100-0
-          Equivalent to H.273 ColourPrimaries code point 9.
         </description>
       </entry>
       <entry name="cie1931_xyz" value="7">
@@ -228,21 +234,18 @@
           space by
           - SMPTE ST 428-1
           - (CIE 1931 XYZ as in ISO 11664-1)
-          Equivalent to H.273 ColourPrimaries code point 10.
         </description>
       </entry>
       <entry name="dci_p3" value="8">
         <description summary="Color primaries of the DCI P3 color space as defined by the SMPTE RP 431 standard">
           Color primaries as defined by Digital Cinema System and published in
-          SMPTE RP 431-2 (2011). Equivalent to H.273 ColourPrimaries code point
-          11.
+          SMPTE RP 431-2 (2011).
         </description>
       </entry>
       <entry name="display_p3" value="9">
         <description summary="Color primaries of Display P3 variant of the DCI-P3 color space as defined by the SMPTE EG 432 standard">
           Color primaries as defined by Digital Cinema System and published in
           SMPTE EG 432-1 (2010).
-          Equivalent to H.273 ColourPrimaries code point 12.
         </description>
       </entry>
       <entry name="adobe_rgb" value="10">
@@ -256,13 +259,11 @@
     <enum name="transfer_function">
       <description summary="named transfer functions">
         Named transfer functions used to represent well-known transfer
-        characteristics. H.273 is the authority, when it comes to the exact
-        formulas and authoritative specifications, where an equivalent code
-        point exists.
+        characteristics of displays.
 
         A value of 0 is invalid and will never be present in the list of enums.
 
-        Descriptions do list the specifications for convenience.
+        See appendix.md for the formulae.
       </description>
 
       <entry name="bt1886" value="1">
@@ -271,8 +272,6 @@
           - Rec. ITU-R BT.601-7 525 and 625
           - Rec. ITU-R BT.709-6
           - Rec. ITU-R BT.2020-2
-          These recommendations are referred to by H.273 TransferCharacteristics
-          code points 1, 6, 14, and 15, which are all equivalent.
 
           This TF implies these default luminances from Rec. ITU-R BT.2035:
           - primary color volume minimum: 0.01 cd/m²
@@ -289,65 +288,57 @@
           - United States Federal Communications Commission (2003) Title 47 Code
             of Federal Regulations 73.682 (a) (20)
           - Rec. ITU-R BT.1700-0 625 PAL and 625 SECAM
-          Equivalent to H.273 TransferCharacteristics code point 4.
+          - IEC 61966-2-1 (reference display)
         </description>
       </entry>
       <entry name="gamma28" value="3">
         <description summary="Assumed display gamma 2.8 transfer function">
           Transfer characteristics as defined by
           - Rec. ITU-R BT.470-6 System B, G (historical)
-          Equivalent to H.273 TransferCharacteristics code point 5.
         </description>
       </entry>
       <entry name="st240" value="4">
         <description summary="SMPTE ST 240 transfer function">
           Transfer characteristics as defined by
           - SMPTE ST 240 (1999)
-          Equivalent to H.273 TransferCharacteristics code point 7.
         </description>
       </entry>
       <entry name="ext_linear" value="5">
         <description summary="extended linear transfer function">
           Linear transfer function defined over all real numbers.
           Normalised electrical values are equal the normalised optical values.
-
-          The differences to H.273 TransferCharacteristics code point 8 are
-          the definition over all real numbers.
         </description>
       </entry>
       <entry name="log_100" value="6">
         <description summary="logarithmic 100:1 transfer function">
           Logarithmic transfer characteristic (100:1 range).
-          Equivalent to H.273 TransferCharacteristics code point 9.
         </description>
       </entry>
       <entry name="log_316" value="7">
         <description summary="logarithmic (100*Sqrt(10) : 1) transfer function">
           Logarithmic transfer characteristic (100 * Sqrt(10) : 1 range).
-          Equivalent to H.273 TransferCharacteristics code point 10.
         </description>
       </entry>
       <entry name="xvycc" value="8">
         <description summary="IEC 61966-2-4 transfer function">
           Transfer characteristics as defined by
           - IEC 61966-2-4
-          Equivalent to H.273 TransferCharacteristics code point 11.
         </description>
       </entry>
-      <entry name="srgb" value="9">
-        <description summary="sRGB piece-wise transfer function">
+      <entry name="srgb" value="9" deprecated-since="2">
+        <description summary="Deprecated (ambiguous sRGB transfer function)">
           Transfer characteristics as defined by
           - IEC 61966-2-1 sRGB
-          Equivalent to H.273 TransferCharacteristics code point 13 with
-          MatrixCoefficients set to 0.
+
+          As a rule of thumb, use gamma22 for video, motion picture and
+          computer graphics, or compound_power_2_4 for ICC calibrated print
+          workflows.
         </description>
       </entry>
-      <entry name="ext_srgb" value="10">
-        <description summary="Extended sRGB piece-wise transfer function">
+      <entry name="ext_srgb" value="10" deprecated-since="2">
+        <description summary="Deprecated (Extended sRGB piece-wise transfer function)">
           Transfer characteristics as defined by
           - IEC 61966-2-1 sYCC
-          Equivalent to H.273 TransferCharacteristics code point 13 with
-          MatrixCoefficients set to anything but 0.
         </description>
       </entry>
       <entry name="st2084_pq" value="11">
@@ -355,7 +346,6 @@
           Transfer characteristics as defined by
           - SMPTE ST 2084 (2014) for 10-, 12-, 14- and 16-bit systems
           - Rec. ITU-R BT.2100-2 perceptual quantization (PQ) system
-          Equivalent to H.273 TransferCharacteristics code point 16.
 
           This TF implies these default luminances
           - primary color volume minimum: 0.005 cd/m²
@@ -373,7 +363,6 @@
         <description summary="SMPTE ST 428 transfer function">
           Transfer characteristics as defined by
           - SMPTE ST 428-1 (2019)
-          Equivalent to H.273 TransferCharacteristics code point 17.
         </description>
       </entry>
       <entry name="hlg" value="13">
@@ -381,7 +370,6 @@
           Transfer characteristics as defined by
           - ARIB STD-B67 (2015)
           - Rec. ITU-R BT.2100-2 hybrid log-gamma (HLG) system
-          Equivalent to H.273 TransferCharacteristics code point 18.
 
           This TF implies these default luminances
           - primary color volume minimum: 0.005 cd/m²
@@ -398,6 +386,12 @@
           ARIB STD-B67 or BT.2100.
         </description>
       </entry>
+      <entry name="compound_power_2_4" value="14" since="2">
+        <description summary="IEC 61966-2-1 encoding function">
+          Encoding characteristics as defined by IEC 61966-2-1, for displays
+          that invert the encoding function.
+        </description>
+      </entry>
     </enum>
 
     <request name="get_output">
@@ -531,6 +525,9 @@
       <description summary="supported rendering intent">
         When this object is created, it shall immediately send this event once
         for each rendering intent the compositor supports.
+
+        A compositor must not advertise intents that are deprecated in the
+        bound version of the interface.
       </description>
 
       <arg name="render_intent" type="uint" enum="render_intent"
@@ -541,6 +538,9 @@
       <description summary="supported features">
         When this object is created, it shall immediately send this event once
         for each compositor supported feature listed in the enumeration.
+
+        A compositor must not advertise features that are deprecated in the
+        bound version of the interface.
       </description>
 
       <arg name="feature" type="uint" enum="feature"
@@ -552,6 +552,9 @@
         When this object is created, it shall immediately send this event once
         for each named transfer function the compositor supports with the
         parametric image description creator.
+
+        A compositor must not advertise transfer functions that are deprecated
+        in the bound version of the interface.
       </description>
 
       <arg name="tf" type="uint" enum="transfer_function"
@@ -563,6 +566,9 @@
         When this object is created, it shall immediately send this event once
         for each named set of primaries the compositor supports with the
         parametric image description creator.
+
+        A compositor must not advertise names that are deprecated in the
+        bound version of the interface.
       </description>
 
       <arg name="primaries" type="uint" enum="primaries"
@@ -575,9 +581,23 @@
         transfer functions and named primaries have been sent.
       </description>
     </event>
+
+    <request name="get_image_description" since="2">
+      <description summary="create an image description from a reference">
+        This request retrieves the image description backing a reference.
+
+        The get_information request can be used if and only if the request that
+        creates the reference allows it.
+      </description>
+
+      <arg name="image_description"
+           type="new_id" interface="wp_image_description_v1"/>
+      <arg name="reference"
+           type="object" interface="wp_image_description_reference_v1"/>
+    </request>
   </interface>
 
-  <interface name="wp_color_management_output_v1" version="1">
+  <interface name="wp_color_management_output_v1" version="2">
     <description summary="output color properties">
       A wp_color_management_output_v1 describes the color properties of an
       output.
@@ -647,7 +667,7 @@
     </request>
   </interface>
 
-  <interface name="wp_color_management_surface_v1" version="1">
+  <interface name="wp_color_management_surface_v1" version="2">
     <description summary="color management extension to a surface">
         A wp_color_management_surface_v1 allows the client to set the color
         space and HDR properties of a surface.
@@ -693,18 +713,18 @@
         All image descriptions which are ready (see wp_image_description_v1)
         are allowed and must always be accepted by the compositor.
 
-        A rendering intent provides the client's preference on how content
-        colors should be mapped to each output. The render_intent value must
-        be one advertised by the compositor with
+        When an image description is set on a surface, it establishes an
+        explicit link between surface pixel values and surface colorimetry.
+        This link may be undefined for some pixel values, see the image
+        description creator interfaces for the conditions. Non-finite
+        floating-point values (NaN, Inf) always have an undefined colorimetry.
+
+        A rendering intent provides the client's preference on how surface
+        colorimetry should be mapped to each output. The render_intent value
+        must be one advertised by the compositor with
         wp_color_manager_v1.render_intent event, otherwise the protocol error
         render_intent is raised.
 
-        When an image description is set on a surface, the Transfer
-        Characteristics of the image description defines the valid range of
-        the nominal (real-valued) color channel values. The processing of
-        out-of-range color channel values is undefined, but compositors are
-        recommended to clamp the values to the valid range when possible.
-
         By default, a surface does not have an associated image description
         nor a rendering intent. The handling of color on such surfaces is
         compositor implementation defined. Compositors should handle such
@@ -735,7 +755,7 @@
     </request>
   </interface>
 
-  <interface name="wp_color_management_surface_feedback_v1" version="1">
+  <interface name="wp_color_management_surface_feedback_v1" version="2">
     <description summary="color management extension to a surface">
         A wp_color_management_surface_feedback_v1 allows the client to get the
         preferred image description of a surface.
@@ -758,27 +778,14 @@
              summary="attempted to use an unsupported feature"/>
     </enum>
 
-    <event name="preferred_changed">
-      <description summary="the preferred image description changed">
-        The preferred image description is the one which likely has the most
-        performance and/or quality benefits for the compositor if used by the
-        client for its wl_surface contents. This event is sent whenever the
-        compositor changes the wl_surface's preferred image description.
-
-        This event sends the identity of the new preferred state as the argument,
-        so clients who are aware of the image description already can reuse it.
-        Otherwise, if the client client wants to know what the preferred image
-        description is, it shall use the get_preferred request.
-
-        The preferred image description is not automatically used for anything.
-        It is only a hint, and clients may set any valid image description with
-        set_image_description, but there might be performance and color accuracy
-        improvements by providing the wl_surface contents in the preferred
-        image description. Therefore clients that can, should render according
-        to the preferred image description
+    <event name="preferred_changed" deprecated-since="2">
+      <description summary="the preferred image description changed (32-bit)">
+        Starting from interface version 2, 'preferred_changed2' is sent instead
+        of this event. See the 'preferred_changed2' event for the definition.
       </description>
 
-      <arg name="identity" type="uint" summary="image description id number"/>
+      <arg name="identity" type="uint"
+           summary="the 32-bit image description id number"/>
     </event>
 
     <request name="get_preferred">
@@ -835,9 +842,38 @@
       <arg name="image_description"
            type="new_id" interface="wp_image_description_v1"/>
     </request>
+
+    <!-- Version 2 additions -->
+
+    <event name="preferred_changed2" since="2">
+      <description summary="the preferred image description changed">
+        The preferred image description is the one which likely has the most
+        performance and/or quality benefits for the compositor if used by the
+        client for its wl_surface contents. This event is sent whenever the
+        compositor changes the wl_surface's preferred image description.
+
+        This event sends the identity of the new preferred state as the argument,
+        so clients who are aware of the image description already can reuse it.
+        Otherwise, if the client client wants to know what the preferred image
+        description is, it shall use the get_preferred request.
+
+        The preferred image description is not automatically used for anything.
+        It is only a hint, and clients may set any valid image description with
+        set_image_description, but there might be performance and color accuracy
+        improvements by providing the wl_surface contents in the preferred
+        image description. Therefore clients that can, should render according
+        to the preferred image description
+      </description>
+
+      <arg name="identity_hi" type="uint"
+           summary="high 32 bits of the 64-bit image description id number"/>
+      <arg name="identity_lo" type="uint"
+           summary="low 32 bits of the 64-bit image description id number"/>
+    </event>
+
   </interface>
 
-  <interface name="wp_image_description_creator_icc_v1" version="1">
+  <interface name="wp_image_description_creator_icc_v1" version="2">
     <description summary="holder of image description ICC information">
       This type of object is used for collecting all the information required
       to create a wp_image_description_v1 object from an ICC file. A complete
@@ -853,6 +889,10 @@
       Once all properties have been set, the create request must be used to
       create the image description object, destroying the creator in the
       process.
+
+      The link between a pixel value (a device value in ICC) and its respective
+      colorimetry is defined by the details of the particular ICC profile.
+      Those details also determine when colorimetry becomes undefined.
     </description>
 
     <enum name="error">
@@ -949,7 +989,7 @@
     </request>
   </interface>
 
-  <interface name="wp_image_description_creator_params_v1" version="1">
+  <interface name="wp_image_description_creator_params_v1" version="2">
     <description summary="holder of image description parameters">
       This type of object is used for collecting all the parameters required
       to create a wp_image_description_v1 object. A complete set of required
@@ -978,6 +1018,20 @@
       Once all properties have been set, the create request must be used to
       create the image description object, destroying the creator in the
       process.
+
+      A viewer, who is viewing the display defined by the resulting image
+      description (the viewing environment included), is assumed to be fully
+      adapted to the primary color volume's white point.
+
+      Any of the following conditions will cause the colorimetry of a pixel
+      to become undefined:
+      - Values outside of the defined range of the transfer characteristic.
+      - Tristimulus that exceeds the target color volume.
+      - If extended_target_volume is not supported: tristimulus that exceeds
+      the primary color volume.
+
+      The closest correspondence to an image description created through this
+      interface is the Display class of profiles in ICC.
     </description>
 
     <enum name="error">
@@ -1006,14 +1060,16 @@
         complete, the protocol error incomplete_set is raised. For the
         definition of a complete set, see the description of this interface.
 
-        The protocol error invalid_luminance is raised if any of the following
-        requirements is not met:
+        When both max_cll and max_fall are set, max_fall must be less or equal
+        to max_cll otherwise the invalid_luminance protocol error is raised.
+
+        In version 1, these following conditions also result in the
+        invalid_luminance protocol error. Version 2 and later do not have this
+        requirement.
         - When max_cll is set, it must be greater than min L and less or equal
           to max L of the mastering luminance range.
         - When max_fall is set, it must be greater than min L and less or equal
           to max L of the mastering luminance range.
-        - When both max_cll and max_fall are set, max_fall must be less or equal
-          to max_cll.
 
         If the particular combination of the parameter set is not supported
         by the compositor, the resulting image description object shall
@@ -1039,7 +1095,7 @@
         functions.
 
         When the resulting image description is attached to an image, the
-        content should be encoded and decoded according to the industry standard
+        content should be decoded according to the industry standard
         practices for the transfer characteristic.
 
         Only names advertised with wp_color_manager_v1 event supported_tf_named
@@ -1061,9 +1117,6 @@
         range of the curve are all finite real numbers. This curve represents
         the conversion from electrical to optical color channel values.
 
-        When the resulting image description is attached to an image, the
-        content should be encoded with the inverse of the power curve.
-
         The curve exponent shall be multiplied by 10000 to get the argument eexp
         value to carry the precision of 4 decimals.
 
@@ -1129,8 +1182,8 @@
     <request name="set_luminances">
       <description summary="primary color volume luminance range and reference white">
         Sets the primary color volume luminance range and the reference white
-        luminance level. These values include the minimum display emission
-        and ambient flare luminances, assumed to be optically additive and have
+        luminance level. These values include the minimum display emission, but
+        not external flare. The minimum display emission is assumed to have
         the chromaticity of the primary color volume white point.
 
         The default luminances from
@@ -1310,13 +1363,15 @@
     </request>
   </interface>
 
-  <interface name="wp_image_description_v1" version="1">
+  <interface name="wp_image_description_v1" version="2">
     <description summary="Colorimetric image description">
-      An image description carries information about the color encoding used on
-      a surface when attached to a wl_surface via
+      An image description carries information about the pixel color encoding
+      and its intended display and viewing environment. The image description is
+      attached to a wl_surface via
       wp_color_management_surface_v1.set_image_description. A compositor can use
       this information to decode pixel values into colorimetrically meaningful
-      quantities.
+      quantities, which allows the compositor to transform the surface contents
+      to become suitable for various displays and viewing environments.
 
       Note, that the wp_image_description_v1 object is not ready to be used
       immediately after creation. The object eventually delivers either the
@@ -1385,8 +1440,43 @@
            summary="ad hoc human-readable explanation"/>
     </event>
 
-    <event name="ready">
-      <description summary="indication that the object is ready to be used">
+    <event name="ready" deprecated-since="2">
+      <description summary="the object is ready to be used (32-bit)">
+        Starting from interface version 2, the 'ready2' event is sent instead
+        of this event.
+
+        For the definition of this event, see the 'ready2' event. The
+        difference to this event is as follows.
+
+        The id number is valid only as long as the protocol object is alive. If
+        all protocol objects referring to the same image description record are
+        destroyed, the id number may be recycled for a different image
+        description record.
+      </description>
+
+      <arg name="identity" type="uint"
+           summary="the 32-bit image description id number"/>
+    </event>
+
+    <request name="get_information">
+      <description summary="get information about the image description">
+        Creates a wp_image_description_info_v1 object which delivers the
+        information that makes up the image description.
+
+        Not all image description protocol objects allow get_information
+        request. Whether it is allowed or not is defined by the request that
+        created the object. If get_information is not allowed, the protocol
+        error no_information is raised.
+      </description>
+
+      <arg name="information"
+           type="new_id" interface="wp_image_description_info_v1"/>
+    </request>
+
+    <!-- Version 2 additions -->
+
+    <event name="ready2" since="2">
+      <description summary="the object is ready to be used">
         Once this event has been sent, the wp_image_description_v1 object is
         deemed "ready". Ready objects can be used to send requests and can be
         used through other interfaces.
@@ -1400,42 +1490,27 @@
         cannot have the same id number simultaneously. The id number does not
         change during the lifetime of the image description record.
 
-        The id number is valid only as long as the protocol object is alive. If
-        all protocol objects referring to the same image description record are
-        destroyed, the id number may be recycled for a different image
-        description record.
-
         Image description id number is not a protocol object id. Zero is
         reserved as an invalid id number. It shall not be possible for a client
         to refer to an image description by its id number in protocol. The id
         numbers might not be portable between Wayland connections. A compositor
         shall not send an invalid id number.
 
+        Compositors must not recycle image description id numbers.
+
         This identity allows clients to de-duplicate image description records
         and avoid get_information request if they already have the image
         description information.
       </description>
 
-      <arg name="identity" type="uint" summary="image description id number"/>
+      <arg name="identity_hi" type="uint"
+           summary="high 32 bits of the 64-bit image description id number"/>
+      <arg name="identity_lo" type="uint"
+           summary="low 32 bits of the 64-bit image description id number"/>
     </event>
-
-    <request name="get_information">
-      <description summary="get information about the image description">
-        Creates a wp_image_description_info_v1 object which delivers the
-        information that makes up the image description.
-
-        Not all image description protocol objects allow get_information
-        request. Whether it is allowed or not is defined by the request that
-        created the object. If get_information is not allowed, the protocol
-        error no_information is raised.
-      </description>
-
-      <arg name="information"
-           type="new_id" interface="wp_image_description_info_v1"/>
-    </request>
   </interface>
 
-  <interface name="wp_image_description_info_v1" version="1">
+  <interface name="wp_image_description_info_v1" version="2">
     <description summary="Colorimetric image description information">
       Sends all matching events describing an image description object exactly
       once and finally sends the 'done' event.
@@ -1628,4 +1703,22 @@
            summary="Maximum frame-average light level (cd/m²)"/>
     </event>
   </interface>
+
+  <interface name="wp_image_description_reference_v1" version="1">
+    <description summary="Reference to an image description">
+      This object is a reference to an image description. This interface is
+      frozen at version 1 to allow other protocols to create
+      wp_image_description_v1 objects.
+
+      The wp_color_manager_v1.get_image_description request can be used to
+      retrieve the underlying image description.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the reference">
+        Destroy this object. This has no effect on the referenced image
+        description.
+      </description>
+    </request>
+  </interface>
 </protocol>