From c6a5da2ea9c48cd238912fb8e325edec32783798 Mon Sep 17 00:00:00 2001 From: Xaver Hugl Date: Thu, 19 Feb 2026 17:39:32 +0100 Subject: [PATCH] backends/waylandbackend: support windows bt2100 image descriptions See https://gitlab.freedesktop.org/wayland/wayland-protocols/-/merge_requests/491 for more details --- protocol/color-management-v1.xml | 383 ++++++++++++++++++++----------- src/Backends/WaylandBackend.cpp | 7 +- 2 files changed, 260 insertions(+), 130 deletions(-) diff --git a/protocol/color-management-v1.xml b/protocol/color-management-v1.xml index ee482c5af1..eb2e869652 100644 --- a/protocol/color-management-v1.xml +++ b/protocol/color-management-v1.xml @@ -31,9 +31,14 @@ 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. - + 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"/> + + + 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. + + @@ -150,17 +164,15 @@ + - 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. @@ -173,7 +185,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. @@ -184,7 +195,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. @@ -194,7 +204,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. @@ -205,13 +214,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. - 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". @@ -219,7 +228,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. @@ -228,21 +236,18 @@ space by - SMPTE ST 428-1 - (CIE 1931 XYZ as in ISO 11664-1) - Equivalent to H.273 ColourPrimaries code point 10. 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). Color primaries as defined by Digital Cinema System and published in SMPTE EG 432-1 (2010). - Equivalent to H.273 ColourPrimaries code point 12. @@ -256,13 +261,11 @@ 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. @@ -271,8 +274,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 +290,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) Transfer characteristics as defined by - Rec. ITU-R BT.470-6 System B, G (historical) - Equivalent to H.273 TransferCharacteristics code point 5. Transfer characteristics as defined by - SMPTE ST 240 (1999) - Equivalent to H.273 TransferCharacteristics code point 7. 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. Logarithmic transfer characteristic (100:1 range). - Equivalent to H.273 TransferCharacteristics code point 9. Logarithmic transfer characteristic (100 * Sqrt(10) : 1 range). - Equivalent to H.273 TransferCharacteristics code point 10. Transfer characteristics as defined by - IEC 61966-2-4 - Equivalent to H.273 TransferCharacteristics code point 11. - - + + 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. - - + + 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. @@ -355,7 +348,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 +365,6 @@ Transfer characteristics as defined by - SMPTE ST 428-1 (2019) - Equivalent to H.273 TransferCharacteristics code point 17. @@ -381,7 +372,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 +388,12 @@ ARIB STD-B67 or BT.2100. + + + Encoding characteristics as defined by IEC 61966-2-1, for displays + that invert the encoding function. + + @@ -531,6 +527,9 @@ 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. 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. + + + + 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. + + + + + + + + + This creates a pre-defined image description for the so-called + Windows-BT.2100 stimulus encoding. This comes from the Windows 10 + handling of its own definition of a BT.2100 color space for an HDR + screen driven in BT.2100/PQ signalling mode. + + Windows-BT.2100 uses BT.2020 color primaries and white point. + The transfer characteristic is st2084_pq. + + Windows-BT.2100 is generally displayed by Windows 10 without any + adjustments to the signal to account for viewing conditions. + + The reference white level of Windows-BT.2100 is unknown. If a + reference white level must be assumed for compositor processing, it + should be 203 cd/m² of Report ITU-R BT.2408-7. + + The target color volume of Windows-BT.2100 is unknown. The color gamut + may be anything up to BT.2100. + + This request can be used when the compositor advertises + wp_color_manager_v1.feature.windows_bt2100. + Otherwise this request raises the protocol error unsupported_feature. + + The resulting image description object does not allow get_information + request. The wp_image_description_v1.ready event shall be sent. + + + + - + A wp_color_management_output_v1 describes the color properties of an output. @@ -647,7 +701,7 @@ - + A wp_color_management_surface_v1 allows the client to set the color space and HDR properties of a surface. @@ -693,18 +747,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 +789,7 @@ - + A wp_color_management_surface_feedback_v1 allows the client to get the preferred image description of a surface. @@ -758,27 +812,14 @@ summary="attempted to use an unsupported feature"/> - - - 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 + + + Starting from interface version 2, 'preferred_changed2' is sent instead + of this event. See the 'preferred_changed2' event for the definition. - + @@ -835,9 +876,38 @@ + + + + + + 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 + + + + + + - + 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 +923,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. @@ -949,7 +1023,7 @@ - + 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 +1052,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. @@ -1006,14 +1094,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 +1129,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 +1151,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 +1216,8 @@ 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 +1397,15 @@ - + - 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 +1474,43 @@ summary="ad hoc human-readable explanation"/> - - + + + 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. + + + + + + + + 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. + + + + + + + + + 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 +1524,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. - + + - - - - 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. - - - - - + Sends all matching events describing an image description object exactly once and finally sends the 'done' event. @@ -1564,9 +1673,7 @@ 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. + color volume is the actually displayable color volume. Each coordinate value is multiplied by 1 million to get the argument value to carry precision of 6 decimals. @@ -1628,4 +1735,22 @@ summary="Maximum frame-average light level (cd/m²)"/> + + + + 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. + + + + + Destroy this object. This has no effect on the referenced image + description. + + + diff --git a/src/Backends/WaylandBackend.cpp b/src/Backends/WaylandBackend.cpp index 964132b2a4..6d97e073f9 100644 --- a/src/Backends/WaylandBackend.cpp +++ b/src/Backends/WaylandBackend.cpp @@ -2039,6 +2039,11 @@ namespace gamescope if ( m_WPColorManagerFeatures.bSupportsGamescopeColorManagement ) { // HDR10. + if (Algorithm::Contains(m_WPColorManagerFeatures.eFeatures, WP_COLOR_MANAGER_V1_FEATURE_WINDOWS_BT2100)) + { + m_pWPImageDescriptions[ GAMESCOPE_APP_TEXTURE_COLORSPACE_HDR10_PQ ] = wp_color_manager_v1_create_windows_bt2100( m_pWPColorManager ); + } + else { wp_image_description_creator_params_v1 *pParams = wp_color_manager_v1_create_parametric_creator( m_pWPColorManager ); wp_image_description_creator_params_v1_set_primaries_named( pParams, WP_COLOR_MANAGER_V1_PRIMARIES_BT2020 ); @@ -2530,7 +2535,7 @@ namespace gamescope } else if ( !strcmp( pInterface, wp_color_manager_v1_interface.name ) ) { - m_pWPColorManager = (wp_color_manager_v1 *)wl_registry_bind( pRegistry, uName, &wp_color_manager_v1_interface, 1u ); + m_pWPColorManager = (wp_color_manager_v1 *)wl_registry_bind( pRegistry, uName, &wp_color_manager_v1_interface, std::min(3u, uVersion) ); wp_color_manager_v1_add_listener( m_pWPColorManager, &s_WPColorManagerListener, this ); } else if ( !strcmp( pInterface, zwp_pointer_constraints_v1_interface.name ) )