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 ) )