Warning, /plasma/kwin/src/wayland/protocols/xx-color-management-v2.xml is written in an unsupported language. File is not indexed.

 <?xml version="1.0" encoding="UTF-8"?>
 <protocol name="xx_color_management_v2">
   <copyright>
     Copyright 2019 Sebastian Wick
     Copyright 2019 Erwin Burema
     Copyright 2020 AMD
     Copyright 2020, 2022, 2023 Collabora, Ltd.
 
     Permission is hereby granted, free of charge, to any person obtaining a
     copy of this software and associated documentation files (the "Software"),
     to deal in the Software without restriction, including without limitation
     the rights to use, copy, modify, merge, publish, distribute, sublicense,
     and/or sell copies of the Software, and to permit persons to whom the
     Software is furnished to do so, subject to the following conditions:
 
     The above copyright notice and this permission notice (including the next
     paragraph) shall be included in all copies or substantial portions of the
     Software.
 
     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
     IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
     FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
     THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
     LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
     FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
     DEALINGS IN THE SOFTWARE.
   </copyright>
 
   <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.
 
     The color properties are represented as an image description object which
     is immutable after it has been created. A wl_output always has an
     associated image description that clients can observe. A wl_surface
     always has an associated preferred image description as a hint chosen by
     the compositor that clients can also observe. Clients can set an image
     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.
 
     Recommendation ITU-T H.273
     "Coding-independent code points for video signal type identification"
     shall be referred to as simply H.273 here.
 
     The color-and-hdr repository
     (https://gitlab.freedesktop.org/pq/color-and-hdr) contains
     background information on the protocol design and legacy color management.
     It also contains a glossary, learning resources for digital color, tools,
     samples and more.
 
     The terminology used in this protocol is based on common color science and
     color encoding terminology where possible. The glossary in the color-and-hdr
     repository shall be the authority on the definition of terms in this
     protocol.
   </description>
 
   <interface name="xx_color_manager_v2" version="1">
     <description summary="color manager singleton">
       A global interface used for getting color management extensions for
       wl_surface and wl_output objects, and for creating client defined image
       description objects. The extension interfaces allow
       getting the image description of outputs and setting the image
       description of surfaces.
     </description>
 
     <request name="destroy" type="destructor">
       <description summary="destroy the color manager">
         Destroy the xx_color_manager_v2 object. This does not affect any other
         objects in any way.
       </description>
     </request>
 
     <enum name="error">
       <entry name="unsupported_feature" value="0" summary="request not supported"/>
     </enum>
 
     <enum name="render_intent">
       <description summary="rendering intents">
         See the ICC.1:2022 specification from the International Color Consortium
         for more details about rendering intents.
 
         The principles of ICC defined rendering intents apply with all types
         of image descriptions, not only those with ICC file profiles.
 
         Compositors must support the perceptual rendering intent. Other
         rendering intents are optional.
       </description>
 
       <entry name="perceptual" value="0" summary="perceptual"/>
       <entry name="relative" value="1" summary="media-relative colorimetric"/>
       <entry name="saturation" value="2" summary="saturation"/>
       <entry name="absolute" value="3" summary="ICC-absolute colorimetric"/>
       <entry name="relative_bpc" value="4"
              summary="media-relative colorimetric + black point compensation"/>
     </enum>
 
     <enum name="feature">
       <description summary="compositor supported features"/>
 
       <entry name="icc_v2_v4" value="0" summary="new_icc_creator request"/>
       <entry name="parametric" value="1" summary="new_parametric_creator request"/>
       <entry name="set_primaries" value="2" summary="parametric set_primaries request"/>
       <entry name="set_tf_power" value="3" summary="parametric set_tf_power request"/>
       <entry name="set_mastering_display_primaries" value="4">
         <description summary="parametric set_mastering_display_primaries request">
           The compositor supports set_mastering_display_primaries request
           with a target color volume fully contained inside the primary
           color volume.
         </description>
       </entry>
       <entry name="extended_target_volume" value="5">
         <description summary="parametric target exceeds primary color volume">
           The compositor additionally supports target color volumes that
           extend outside of the primary color volume.
 
           This can only be advertised if feature set_mastering_display_primaries
           is supported as well.
         </description>
       </entry>
     </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.
         Descriptions do list the specifications for convenience.
       </description>
       <entry name="srgb" value="0">
         <description summary="Color primaries for the sRGB color space as defined by the BT.709 standard">
           Color primaries as defined by
           - Rec. ITU-R BT.709-6
           - Rec. ITU-R BT.1361-0 conventional colour gamut system and extended colour gamut system (historical)
           - IEC 61966-2-1 sRGB or sYCC
           - 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="1">
         <description summary="Color primaries for PAL-M as defined by the BT.470 standard">
           Color primaries as defined by
           - Rec. ITU-R BT.470-6 System M (historical)
           - United States National Television System Committee 1953 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="2">
         <description summary="Color primaries for PAL as defined by the BT.601 standard">
           Color primaries as defined by
           - Rec. ITU-R BT.470-6 System B, G (historical)
           - 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="3">
         <description summary="Color primaries for NTSC as defined by the BT.601 standard">
           Color primaries as defined by
           - Rec. ITU-R BT.601-7 525
           - Rec. ITU-R BT.1358-1 525 or 625 (historical)
           - 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="4">
         <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.
         </description>
       </entry>
       <entry name="bt2020" value="5">
         <description summary="Color primaries as defined by the BT.2020 and BT.2100 standard">
           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="6">
         <description summary="Color primaries of the full CIE 1931 XYZ color space">
           Color primaries as defined as the maximum of the CIE 1931 XYZ color 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="7">
         <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.
         </description>
       </entry>
       <entry name="display_p3" value="8">
         <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="9">
         <description summary="Color primaries of the Adobe RGB color space as defined by the ISO 12640 standard">
           Color primaries as defined by Adobe as "Adobe RGB" and later published by ISO 12640-4 (2011).
         </description>
       </entry>
     </enum>
 
     <enum name="transfer_function">
       <description summary="named transfer functions">
         Named Transfer Functions.
       </description>
       <entry name="bt709" value="0">
         <description summary="BT.709 transfer function">
           Transfer characteristics as defined by
           - Rec. ITU-R BT.709-6
           - Rec. ITU-R BT.1361-0 conventional colour gamut system (historical)
           Equivalent to H.273 TransferCharacteristics code point 1, 6, 14, 15.
         </description>
       </entry>
       <entry name="gamma22" value="1">
         <description summary="Assumed display gamma 2.2 transfer function">
           Transfer characteristics as defined by
           - Rec. ITU-R BT.470-6 System M (historical)
           - United States National Television System Committee 1953 Recommendation for transmission standards for color television
           - 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.
         </description>
       </entry>
       <entry name="gamma28" value="2">
         <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="3">
         <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="linear" value="4">
         <description summary="linear transfer function">
           Linear transfer characteristics.
           Equivalent to H.273 TransferCharacteristics code point 8.
         </description>
       </entry>
       <entry name="log_100" value="5">
         <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="6">
         <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="7">
         <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="bt1361" value="8">
         <description summary="BT.1361 extended transfer function">
           Transfer characteristics as defined by
           - Rec. ITU-R BT.1361-0 extended colour gamut system (historical)
           Equivalent to H.273 TransferCharacteristics code point 12.
         </description>
       </entry>
       <entry name="srgb" value="9">
         <description summary="sRGB piece-wise 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.
         </description>
       </entry>
       <entry name="ext_srgb" value="10">
         <description summary="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">
         <description summary="perceptual quantizer transfer function">
           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.
         </description>
       </entry>
       <entry name="st428" value="12">
         <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">
         <description summary="hybrid log-gamma transfer function">
           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.
         </description>
       </entry>
     </enum>
 
     <request name="get_output">
       <description summary="create a color management interface for a wl_output">
         This creates a new xx_color_management_output_v2 object for the
         given wl_output.
 
         See the xx_color_management_output_v2 interface for more details.
       </description>
 
       <arg name="id" type="new_id" interface="xx_color_management_output_v2"/>
       <arg name="output" type="object" interface="wl_output"/>
     </request>
 
     <request name="get_surface">
       <description summary="create a color management interface for a wl_surface">
         This creates a new color xx_color_management_surface_v2 object for the
         given wl_surface.
 
         See the xx_color_management_surface_v2 interface for more details.
       </description>
 
       <arg name="id" type="new_id" interface="xx_color_management_surface_v2"/>
       <arg name="surface" type="object" interface="wl_surface"/>
     </request>
 
     <request name="new_icc_creator">
       <description summary="make a new ICC-based image description creator object">
         Makes a new ICC-based image description creator object with all
         properties initially unset. The client can then use the object's
         interface to define all the required properties for an image description
         and finally create a xx_image_description_v2 object.
 
         This request can be used when the compositor advertises
         xx_color_manager_v2.feature.icc_v2_v4.
         Otherwise this request raises the protocol error unsupported_feature.
       </description>
 
       <arg name="obj" type="new_id"
            interface="xx_image_description_creator_icc_v2"
            summary="the new creator object"/>
     </request>
 
     <request name="new_parametric_creator">
       <description summary="make a new parametric image description creator object">
         Makes a new parametric image description creator object with all
         properties initially unset. The client can then use the object's
         interface to define all the required properties for an image description
         and finally create a xx_image_description_v2 object.
 
         This request can be used when the compositor advertises
         xx_color_manager_v2.feature.parametric.
         Otherwise this request raises the protocol error unsupported_feature.
       </description>
 
       <arg name="obj" type="new_id"
            interface="xx_image_description_creator_params_v2"
            summary="the new creator object"/>
     </request>
 
     <event name="supported_intent">
       <description summary="supported rendering intent">
         When this object is created, it shall immediately send this event
         once for each rendering intent the compositor supports.
       </description>
 
       <arg name="render_intent" type="uint" enum="render_intent"
            summary="rendering intent"/>
     </event>
 
     <event name="supported_feature">
       <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.
       </description>
 
       <arg name="feature" type="uint" enum="feature" summary="supported feature"/>
     </event>
 
     <event name="supported_tf_named">
       <description summary="supported named transfer characteristic">
         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.
       </description>
 
       <arg name="tf" type="uint" enum="transfer_function" summary="Named transfer function"/>
     </event>
 
     <event name="supported_primaries_named">
       <description summary="supported named primaries">
         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.
       </description>
 
       <arg name="primaries" type="uint" enum="primaries" summary="Named color primaries"/>
     </event>
   </interface>
 
   <interface name="xx_color_management_output_v2" version="1">
     <description summary="output color properties">
       A xx_color_management_output_v2 describes the color properties of an
       output.
 
       The xx_color_management_output_v2 is associated with the wl_output global
       underlying the wl_output object. Therefore the client destroying the
       wl_output object has no impact, but the compositor removing the output
       global makes the xx_color_management_output_v2 object inert.
     </description>
 
     <request name="destroy" type="destructor">
       <description summary="destroy the color management output">
         Destroy the color xx_color_management_output_v2 object. This does not
         affect any remaining protocol objects.
       </description>
     </request>
 
     <event name="image_description_changed">
       <description summary="image description changed">
         This event is sent whenever the image description of the
         output changed, followed by one wl_output.done event common to
         output events across all extensions.
 
         If the client wants to use the updated image description, it needs
         to do get_image_description again, because image description objects
         are immutable.
       </description>
     </event>
 
     <request name="get_image_description">
       <description summary="get the image description of the output">
         This creates a new xx_image_description_v2 object for the current image description
         of the output. There always is exactly one image description active for an
         output so the client should destroy the image description created by earlier
         invocations of this request. This request is usually sent as a reaction
         to the image_description_changed event or when creating a
         xx_color_management_output_v2 object.
 
         The created xx_image_description_v2 object preserves the image description
         of the output from the time the object was created.
 
         The resulting image description object allows get_information request.
 
         If this protocol object is inert, the resulting image
         description object shall immediately deliver the
         xx_image_description_v2.failed event with the no_output cause.
 
         If the interface version is inadequate for the output's image
         description, meaning that the client does not support all the
         events needed to deliver the crucial information, the resulting image
         description object shall immediately deliver the
         xx_image_description_v2.failed event with the low_version cause.
 
         Otherwise the object shall immediately deliver the ready event.
       </description>
 
       <arg name="image_description" type="new_id" interface="xx_image_description_v2"/>
     </request>
   </interface>
 
   <interface name="xx_color_management_surface_v2" version="1">
     <description summary="color management extension to a surface">
         A xx_color_management_surface_v2 allows the client to set the color
         space and HDR properties of a surface.
 
         If the wl_surface associated with the xx_color_management_surface_v2 is
         destroyed, the xx_color_management_surface_v2 object becomes inert.
     </description>
 
     <request name="destroy" type="destructor">
       <description summary="destroy the color management interface for a surface">
         Destroy the xx_color_management_surface_v2 object.
 
         When the last xx_color_management_surface_v2 object for a wl_surface
         is destroyed, it does the same as unset_image_description.
       </description>
     </request>
 
     <enum name="error">
       <description summary="protocol errors"/>
 
       <entry name="inert" value="0" summary="forbidden request on inert object"/>
       <entry name="render_intent" value="1" summary="unsupported rendering intent"/>
     </enum>
 
     <request name="set_image_description">
       <description summary="set the surface image description">
         Set the image description of the underlying surface. The image
         description and rendering intent are double-buffered state, see
         wl_surface.commit.
 
         It is the client's responsibility to understand the image description
         it sets on a surface, and to provide content that matches that image
         description.
 
         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
         xx_color_manager_v2.render_intent event, otherwise the protocol error
         render_intent is raised.
 
         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
         surfaces as sRGB but may handle them differently if they have specific
         requirements.
       </description>
 
       <arg name="image_description" type="object" interface="xx_image_description_v2"/>
       <arg name="render_intent" type="uint" enum="xx_color_manager_v2.render_intent"
            summary="rendering intent"/>
     </request>
 
     <request name="unset_image_description">
       <description summary="remove the surface image description">
         This request removes any image description from the surface. See
         set_image_description for how a compositor handles a surface without
         an image description. This is double-buffered state, see
         wl_surface.commit.
       </description>
     </request>
 
     <event name="preferred_changed">
       <description summary="compositor's preferred image description for the surface">
         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 is not an initial event.
 
         This event is merely a notification. When the 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>
     </event>
 
     <request name="get_preferred">
       <description summary="get the preferred image description">
         If this protocol object is inert, the protocol error inert is raised.
 
         This creates a new xx_image_description_v2 object for the currently
         preferred image description for the wl_surface. The client should
         stop using and destroy the image descriptions created by earlier
         invocations of this request for the associated wl_surface.
         This request is usually sent as a reaction to the preferred_changed
         event or when creating a xx_color_management_surface_v2 object if
         the client is capable of adapting to image descriptions.
 
         The created xx_image_description_v2 object preserves the preferred image
         description of the wl_surface from the time the object was created.
 
         The resulting image description object allows get_information request.
 
         If the interface version is inadequate for the preferred image
         description, meaning that the client does not support all the
         events needed to deliver the crucial information, the resulting image
         description object shall immediately deliver the
         xx_image_description_v2.failed event with the low_version cause,
         otherwise the object shall immediately deliver the ready event.
       </description>
 
       <arg name="image_description" type="new_id" interface="xx_image_description_v2"/>
     </request>
   </interface>
 
   <interface name="xx_image_description_creator_icc_v2" version="1">
     <description summary="holder of image description ICC information">
       This type of object is used for collecting all the information required
       to create a xx_image_description_v2 object from an ICC file. A complete
       set of required parameters consists of these properties:
       - ICC file
 
       Each required property must be set exactly once if the client is to create
       an image description. The set requests verify that a property was not
       already set. The create request verifies that all required properties are
       set. There may be several alternative requests for setting each property,
       and in that case the client must choose one of them.
 
       Once all properties have been set, the create request must be used to
       create the image description object, destroying the creator in the
       process.
     </description>
 
     <enum name="error">
       <description summary="protocol errors"/>
 
       <entry name="incomplete_set" value="0" summary="incomplete parameter set"/>
       <entry name="already_set" value="1" summary="property already set"/>
       <entry name="bad_fd" value="2" summary="fd not seekable and readable"/>
       <entry name="bad_size" value="3" summary="no or too much data"/>
       <entry name="out_of_file" value="4" summary="offset + length exceeds file size"/>
     </enum>
 
     <request name="create" type="destructor">
       <description summary="Create the image description object from ICC data">
         Create an image description object based on the ICC information
         previously set on this object. A compositor must parse the ICC data in
         some undefined but finite amount of time.
 
         The completeness of the parameter set is verified. If the set is not
         complete, the protocol error incomplete_set is raised. For the
         definition of a complete set, see the description of this interface.
 
         If the particular combination of the information is not supported
         by the compositor, the resulting image description object shall
         immediately deliver the xx_image_description_v2.failed event with the
         'unsupported' cause. If a valid image description was created from the
         information, the xx_image_description_v2.ready event will eventually
         be sent instead.
 
         This request destroys the xx_image_description_creator_icc_v2 object.
 
         The resulting image description object does not allow get_information
         request.
       </description>
 
       <arg name="image_description" type="new_id" interface="xx_image_description_v2"/>
     </request>
 
     <request name="set_icc_file">
       <description summary="set the ICC profile file">
         Sets the ICC profile file to be used as the basis of the image
         description.
 
         The data shall be found through the given fd at the given offset,
         having the given length. The fd must seekable and readable. Violating
         these requirements raises the bad_fd protocol error.
 
         If reading the data fails due to an error independent of the client, the
         compositor shall send the xx_image_description_v2.failed event on the
         created xx_image_description_v2 with the 'operating_system' cause.
 
         The maximum size of the ICC profile is 4 MB. If length is greater
         than that or zero, the protocol error bad_size is raised.
         If offset + length exceeds the file size, the protocol error
         out_of_file is raised.
 
         A compositor may read the file at any time starting from this request
         and only until whichever happens first:
         - If create request was issued, the xx_image_description_v2 object
           delivers either failed or ready event; or
         - if create request was not issued, this
           xx_image_description_creator_icc_v2 object is destroyed.
 
         A compositor shall not modify the contents of the file, and the fd may
         be sealed for writes and size changes. The client must ensure to its
         best ability that the data does not change while the compositor is
         reading it.
 
         The data must represent a valid ICC profile.
         The ICC profile version must be 2 or 4, it must be a 3 channel profile
         and the class must be 'display'.
         Violating these requirements will not result in a protocol error but
         will eventually send the xx_image_description_v2.failed event on the
         created xx_image_description_v2 with the 'unsupported' cause.
 
         See the International Color Consortium specification ICC.1:2022 for more
         details about ICC profiles.
 
         If ICC file has already been set on this object, the protocol error
         already_set is raised.
       </description>
 
       <arg name="icc_profile" type="fd" summary="ICC profile"/>
       <arg name="offset" type="uint" summary="byte offset in fd to start of ICC data"/>
       <arg name="length" type="uint" summary="length of ICC data in bytes"/>
     </request>
   </interface>
 
   <interface name="xx_image_description_creator_params_v2" version="1">
     <description summary="holder of image description parameters">
       This type of object is used for collecting all the parameters required
       to create a xx_image_description_v2 object. A complete set of required
       parameters consists of these properties:
       - transfer characteristic function (tf)
       - chromaticities of primaries and white point (primary color volume)
 
       The following properties are optional and have a well-defined default
       if not explicitly set:
       - mastering display primaries and white point (target color volume)
       - mastering luminance range
       - maximum content light level
       - maximum frame-average light level
 
       Each required property must be set exactly once if the client is to create
       an image description. The set requests verify that a property was not
       already set. The create request verifies that all required properties are
       set. There may be several alternative requests for setting each property,
       and in that case the client must choose one of them.
 
       Once all properties have been set, the create request must be used to
       create the image description object, destroying the creator in the
       process.
     </description>
 
     <enum name="error">
       <description summary="protocol errors"/>
 
       <entry name="incomplete_set" value="0" summary="incomplete parameter set"/>
       <entry name="inconsistent_set" value="1" summary="invalid combination of parameters"/>
       <entry name="already_set" value="2" summary="property already set"/>
       <entry name="invalid_tf" value="3" summary="invalid transfer characteristic"/>
       <entry name="invalid_primaries" value="4" summary="invalid primaries or white point"/>
       <entry name="invalid_luminance" value="5" summary="invalid luminance value or range"/>
       <entry name="invalid_mastering" value="6" summary="invalid mastering information"/>
     </enum>
 
     <request name="create" type="destructor">
       <description summary="Create the image description object using params">
         Create an image description object based on the parameters previously
         set on this object.
 
         The completeness of the parameter set is verified. If the set is not
         complete, the protocol error incomplete_set is raised. For the
         definition of a complete set, see the description of this interface.
 
         If the particular combination of the parameter set is not supported
         by the compositor, the resulting image description object shall
         immediately deliver the xx_image_description_v2.failed event with the
         'unsupported' cause. If a valid image description was created from the
         parameter set, the xx_image_description_v2.ready event will eventually
         be sent instead.
 
         This request destroys the xx_image_description_creator_params_v2
         object.
 
         The resulting image description object does not allow get_information
         request.
       </description>
 
       <arg name="image_description" type="new_id" interface="xx_image_description_v2"/>
     </request>
 
     <request name="set_tf_named">
       <description summary="named transfer characteristic">
         Sets the transfer characteristic using explicitly enumerated named functions.
 
         Only names advertised with xx_color_manager_v2
         event supported_tf_named are allowed. Other values shall raise the
         protocol error invalid_tf.
 
         If transfer characteristic has already been set on this object, the
         protocol error already_set is raised.
       </description>
 
       <arg name="tf" type="uint" enum="transfer_function" summary="named transfer function"/>
     </request>
 
     <request name="set_tf_power">
       <description summary="transfer characteristic as a power curve">
         Sets the color component transfer characteristic to a power curve
         with the given exponent. This curve represents the conversion from
         electrical to optical pixel or color values.
 
         The curve exponent shall be multiplied by 10000 to get the argument
         eexp value to carry the precision of 4 decimals.
 
         The curve exponent must be at least 1.0 and at most 10.0. Otherwise
         the protocol error invalid_tf is raised.
 
         If transfer characteristic has already been set on this object, the
         protocol error already_set is raised.
 
         This request can be used when the compositor advertises
         xx_color_manager_v2.feature.set_tf_power. Otherwise this request raises
         the protocol error invalid_tf.
       </description>
 
       <arg name="eexp" type="uint" summary="the exponent * 10000"/>
     </request>
 
     <request name="set_primaries_named">
       <description summary="named primaries">
         Sets the color primaries and white point using explicitly named sets.
         This describes the primary color volume which is the basis
         for color value encoding.
 
         Only names advertised with xx_color_manager_v2
         event supported_primaries_named are allowed. Other values shall raise the
         protocol error invalid_primaries.
 
         If primaries have already been set on this object, the protocol error
         already_set is raised.
       </description>
 
       <arg name="primaries" type="uint" enum="primaries" summary="named primaries"/>
     </request>
 
     <request name="set_primaries">
       <description summary="primaries as chromaticity coordinates">
         Sets the color primaries and white point using CIE 1931 xy
         chromaticity coordinates. This describes the primary color volume
         which is the basis for color value encoding.
 
         Each coordinate value is multiplied by 10000 to get the argument
         value to carry precision of 4 decimals.
 
         If primaries have already been set on this object, the protocol error
         already_set is raised.
 
         This request can be used if the compositor advertises
         xx_color_manager_v2.feature.set_primaries. Otherwise this request
         raises the protocol error invalid_primaries.
       </description>
 
       <arg name="r_x" type="uint" summary="Red x * 10000"/>
       <arg name="r_y" type="uint" summary="Red y * 10000"/>
       <arg name="g_x" type="uint" summary="Green x * 10000"/>
       <arg name="g_y" type="uint" summary="Green y * 10000"/>
       <arg name="b_x" type="uint" summary="Blue x * 10000"/>
       <arg name="b_y" type="uint" summary="Blue y * 10000"/>
       <arg name="w_x" type="uint" summary="White x * 10000"/>
       <arg name="w_y" type="uint" summary="White y * 10000"/>
     </request>
 
     <request name="set_mastering_display_primaries">
       <description summary="mastering display primaries as chromaticity coordinates">
         Provides the color primaries and white point of the mastering display
         using CIE 1931 xy chromaticity coordinates. This is compatible with the
         SMPTE ST 2086 definition of HDR static metadata.
 
         The mastering display primaries define the target color volume.
 
         If mastering display primaries are not explicitly set, the target
         color volume is assumed to be equal to the primary color volume.
 
         The target color volume is defined by all tristimulus values between 0.0
         and 1.0 (inclusive) of the color space defined by the given mastering
         display primaries and white point. The colorimetry is identical between
         the container color space and the mastering display color space,
         including that no chromatic adaptation is applied even if the white
         points differ.
 
         The target color volume can exceed the primary color volume to allow for
         a greater color volume with an existing color space definition (for
         example scRGB). It can be smaller than the primary color volume to
         minimize gamut and tone mapping distances for big color spaces (HDR
         metadata).
 
         To make use of the entire target color volume a suitable pixel format
         has to be chosen (e.g. floating point to exceed the primary color
         volume, or abusing limited quantization range as with xvYCC).
 
         Each coordinate value is multiplied by 10000 to get the argument
         value to carry precision of 4 decimals.
 
         If mastering display primaries have already been set on this object,
         the protocol error already_set is raised.
 
         This request can be used if the compositor advertises
         xx_color_manager_v2.feature.set_mastering_display_primaries.
         Otherwise this request raises the protocol error invalid_mastering.
         The advertisement implies support only for target color
         volumes fully contained within the primary color volume.
 
         If a compositor additionally supports target color volume exceeding
         the primary color volume, it must advertise
         xx_color_manager_v2.feature.extended_target_volume.
         If a client uses target color volume exceeding the primary color volume
         and the compositor does not support it, the result is implementation
         defined. Compositors are recommended to detect this case and fail the
         image description gracefully, but it may as well result in color
         artifacts.
       </description>
 
       <arg name="r_x" type="uint" summary="Red x * 10000"/>
       <arg name="r_y" type="uint" summary="Red y * 10000"/>
       <arg name="g_x" type="uint" summary="Green x * 10000"/>
       <arg name="g_y" type="uint" summary="Green y * 10000"/>
       <arg name="b_x" type="uint" summary="Blue x * 10000"/>
       <arg name="b_y" type="uint" summary="Blue y * 10000"/>
       <arg name="w_x" type="uint" summary="White x * 10000"/>
       <arg name="w_y" type="uint" summary="White y * 10000"/>
     </request>
 
     <request name="set_mastering_luminance">
       <description summary="display mastering luminance range">
         Sets the luminance range that was used during the content mastering
         process as the minimum and maximum absolute luminance L. This is
         compatible with the SMPTE ST 2086 definition of HDR static metadata.
 
         This can only be set when set_tf_cicp is used to set the transfer
         characteristic to Rec. ITU-R BT.2100-2 perceptual quantization system.
         Otherwise, 'create' request shall raise inconsistent_set protocol
         error.
 
         The mastering luminance range is undefined by default.
 
         If max L is less than or equal to min L, the protocol error
         invalid_luminance is raised.
 
         Min L value is multiplied by 10000 to get the argument min_lum value
         and carry precision of 4 decimals. Max L value is unscaled for max_lum.
       </description>
 
       <arg name="min_lum" type="uint" summary="min L (cd/m²) * 10000"/>
       <arg name="max_lum" type="uint" summary="max L (cd/m²)"/>
     </request>
 
     <request name="set_max_cll">
       <description summary="maximum content light level">
         Sets the maximum content light level (max_cll) as defined by CTA-861-H.
 
         This can only be set when set_tf_cicp is used to set the transfer
         characteristic to Rec. ITU-R BT.2100-2 perceptual quantization system.
         Otherwise, 'create' request shall raise inconsistent_set protocol
         error.
 
         max_cll is undefined by default.
       </description>
 
       <arg name="max_cll" type="uint" summary="Maximum content light level (cd/m²)"/>
     </request>
 
     <request name="set_max_fall">
       <description summary="maximum frame-average light level">
         Sets the maximum frame-average light level (max_fall) as defined by
         CTA-861-H.
 
         This can only be set when set_tf_cicp is used to set the transfer
         characteristic to Rec. ITU-R BT.2100-2 perceptual quantization system.
         Otherwise, 'create' request shall raise inconsistent_set protocol
         error.
 
         max_fall is undefined by default.
       </description>
 
       <arg name="max_fall" type="uint" summary="Maximum frame-average light level (cd/m²)"/>
     </request>
   </interface>
 
   <interface name="xx_image_description_v2" version="1">
     <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
       xx_color_management_surface_v2.set_image_description. A compositor can
       use this information to decode pixel values into colorimetrically
       meaningful quantities.
 
       Note, that the xx_image_description_v2 object is not ready to be used
       immediately after creation. The object eventually delivers either the
       'ready' or the 'failed' event, specified in all requests creating it. The
       object is deemed "ready" after receiving the 'ready' event.
 
       An object which is not ready is illegal to use, it can only be destroyed.
       Any other request in this interface shall result in the 'not_ready'
       protocol error. Attempts to use an object which is not ready through other
       interfaces shall raise protocol errors defined there.
 
       Once created and regardless of how it was created, a xx_image_description_v2
       object always refers to one fixed image description. It cannot change
       after creation.
     </description>
 
     <request name="destroy" type="destructor">
       <description summary="destroy the image description">
         Destroy this object. It is safe to destroy an object which is not ready.
 
         Destroying a xx_image_description_v2 object has no side-effects, not
         even if a xx_color_management_surface_v2.set_image_description has
         not yet been followed by a wl_surface.commit.
       </description>
     </request>
 
     <enum name="error">
       <description summary="protocol errors"/>
 
       <entry name="not_ready" value="0" summary="attempted to use an object which is not ready"/>
       <entry name="no_information" value="1" summary="get_information not allowed"/>
     </enum>
 
     <enum name="cause">
       <description summary="generic reason for failure"/>
 
       <entry name="low_version" value="0" summary="interface version too low"/>
       <entry name="unsupported" value="1" summary="unsupported image description data"/>
       <entry name="operating_system" value="2" summary="error independent of the client"/>
       <entry name="no_output" value="3" summary="the relevant output no longer exists"/>
     </enum>
 
     <event name="failed">
       <description summary="graceful error on creating the image description">
         If creating a xx_image_description_v2 object fails for a reason that
         is not defined as a protocol error, this event is sent.
         The requests that create image description objects define whether
         and when this can occur. Only such creation requests can trigger this
         event. This event cannot be triggered after the image description was
         successfully formed.
 
         Once this event has been sent, the xx_image_description_v2 object will
         never become ready and it can only be destroyed.
       </description>
 
       <arg name="cause" type="uint" enum="cause" summary="generic reason"/>
       <arg name="msg" type="string" summary="ad hoc human-readable explanation"/>
     </event>
 
     <event name="ready">
       <description summary="indication that the object is ready to be used">
         Once this event has been sent, the xx_image_description_v2 object is
         deemed "ready". Ready objects can be used to send requests and can be
         used through other interfaces.
 
         Every ready xx_image_description_v2 protocol object refers to an
         underlying image description record in the compositor. Multiple protocol
         objects may end up referring to the same record. Clients may identify
         these "copies" by comparing their id numbers: if the numbers from two
         protocol objects are identical, the protocol objects refer to the same
         image description record. Two different image description records
         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.
 
         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"/>
     </event>
 
     <request name="get_information">
       <description summary="get information about the image description">
         Creates a xx_image_description_info_v2 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="xx_image_description_info_v2"/>
     </request>
   </interface>
 
   <interface name="xx_image_description_info_v2" version="1">
     <description summary="Colorimetric image description information">
       Sends all matching events describing an image description object exactly
       once and finally sends the 'done' event.
 
       Once a xx_image_description_info_v2 object has delivered a 'done' event
       it is automatically destroyed.
 
       Every xx_image_description_info_v2 created from the same
       xx_image_description_v2 shall always return the exact same data.
     </description>
 
     <event name="done" type="destructor">
       <description summary="end of information">
         Signals the end of information events and destroys the object.
       </description>
     </event>
 
     <event name="icc_file">
       <description summary="ICC profile matching the image description">
         The icc argument provides a file descriptor to the client which may be
         memory-mapped to provide the ICC profile matching the image description.
         The fd is read-only, and if mapped then it must be mapped with
         MAP_PRIVATE by the client.
 
         The ICC profile version and other details are determined by the
         compositor. There is no provision for a client to ask for a specific
         kind of a profile.
       </description>
 
       <arg name="icc" type="fd" summary="ICC profile file descriptor"/>
       <arg name="icc_size" type="uint" summary="ICC profile size, in bytes"/>
       <!-- Offset always 0, compositor must not expose unnecessary data. -->
     </event>
 
     <event name="primaries">
       <description summary="primaries as chromaticity coordinates">
         Delivers the primary color volume primaries and white point
         using CIE 1931 xy chromaticity coordinates.
 
         Each coordinate value is multiplied by 10000 to get the argument
         value to carry precision of 4 decimals.
       </description>
 
       <arg name="r_x" type="uint" summary="Red x * 10000"/>
       <arg name="r_y" type="uint" summary="Red y * 10000"/>
       <arg name="g_x" type="uint" summary="Green x * 10000"/>
       <arg name="g_y" type="uint" summary="Green y * 10000"/>
       <arg name="b_x" type="uint" summary="Blue x * 10000"/>
       <arg name="b_y" type="uint" summary="Blue y * 10000"/>
       <arg name="w_x" type="uint" summary="White x * 10000"/>
       <arg name="w_y" type="uint" summary="White y * 10000"/>
     </event>
 
     <event name="primaries_named">
       <description summary="named primaries">
         Delivers the primary color volume primaries and white point using a
         explicitly enumerated named set.
       </description>
 
       <arg name="primaries" type="uint" enum="xx_color_manager_v2.primaries" summary="named primaries"/>
     </event>
 
     <event name="tf_power">
       <description summary="transfer characteristic as a power curve">
         The color component transfer characteristic of this image description
         is a pure power curve. This event provides the exponent of the power
         function. This curve represents the conversion from electrical to
         optical pixel or color values.
 
         The curve exponent has been multiplied by 10000 to get the argument
         eexp value to carry the precision of 4 decimals.
       </description>
 
       <arg name="eexp" type="uint" summary="the exponent * 10000"/>
     </event>
 
     <event name="tf_named">
       <description summary="named transfer characteristic">
         Delivers the transfer characteristic using an explicitly enumerated
         named function.
       </description>
 
       <arg name="tf" type="uint" enum="xx_color_manager_v2.transfer_function" summary="named transfer function"/>
     </event>
 
     <event name="target_primaries">
       <description summary="target primaries as chromaticity coordinates">
         Provides the color primaries and white point of the target
         color volume using CIE 1931 xy chromaticity coordinates. This is
         compatible with the SMPTE ST 2086 definition of HDR static metadata
         for mastering displays.
 
         While primary color volume is about how color is encoded, the
         target color volume is the actually displayable color volume.
         If target color volume is equal to the primary color volume,
         then this event is not sent.
 
         Each coordinate value is multiplied by 10000 to get the argument
         value to carry precision of 4 decimals.
       </description>
 
       <arg name="r_x" type="uint" summary="Red x * 10000"/>
       <arg name="r_y" type="uint" summary="Red y * 10000"/>
       <arg name="g_x" type="uint" summary="Green x * 10000"/>
       <arg name="g_y" type="uint" summary="Green y * 10000"/>
       <arg name="b_x" type="uint" summary="Blue x * 10000"/>
       <arg name="b_y" type="uint" summary="Blue y * 10000"/>
       <arg name="w_x" type="uint" summary="White x * 10000"/>
       <arg name="w_y" type="uint" summary="White y * 10000"/>
     </event>
 
     <event name="target_luminance">
       <description summary="target luminance range">
         Provides the luminance range that the image description is targeting
         as the minimum and maximum absolute luminance L. This is compatible
         with the SMPTE ST 2086 definition of HDR static metadata.
 
         This luminance range is only theoretical and may not correspond to the
         luminance of light emitted on an actual display.
 
         Min L value is multiplied by 10000 to get the argument min_lum value
         and carry precision of 4 decimals. Max L value is unscaled for max_lum.
       </description>
 
       <arg name="min_lum" type="uint" summary="min L (cd/m²) * 10000"/>
       <arg name="max_lum" type="uint" summary="max L (cd/m²)"/>
     </event>
 
     <event name="target_max_cll">
       <description summary="target maximum content light level">
         Provides the targeted max_cll of the image description. max_cll is
         defined by CTA-861-H.
 
         This luminance is only theoretical and may not correspond to the
         luminance of light emitted on an actual display.
       </description>
 
       <arg name="max_cll" type="uint" summary="Maximum content light-level (cd/m²)"/>
     </event>
 
     <event name="target_max_fall">
       <description summary="target maximum frame-average light level">
         Provides the targeted max_fall of the image description. max_fall is
         defined by CTA-861-H.
 
         This luminance is only theoretical and may not correspond to the
         luminance of light emitted on an actual display.
       </description>
 
       <arg name="max_fall" type="uint" summary="Maximum frame-average light level (cd/m²)"/>
     </event>
   </interface>
 </protocol>