diff --git a/meson.build b/meson.build index b9a32c8..1624a40 100644 --- a/meson.build +++ b/meson.build @@ -47,6 +47,7 @@ unstable_protocols = { staging_protocols = { 'alpha-modifier': ['v1'], 'color-management': ['v1'], + 'color-representation': ['v1'], 'commit-timing': ['v1'], 'content-type': ['v1'], 'cursor-shape': ['v1'], diff --git a/staging/color-representation/README b/staging/color-representation/README new file mode 100644 index 0000000..5665025 --- /dev/null +++ b/staging/color-representation/README @@ -0,0 +1,6 @@ +color-representation protocol + +Maintainers: +Simon Ser +Sebastian Wick +Pekka Paalanen diff --git a/staging/color-representation/color-representation-v1.xml b/staging/color-representation/color-representation-v1.xml new file mode 100644 index 0000000..c23682f --- /dev/null +++ b/staging/color-representation/color-representation-v1.xml @@ -0,0 +1,428 @@ + + + + Copyright 2022 Simon Ser + Copyright 2022 Red Hat, Inc. + Copyright 2022 Collabora, Ltd. + Copyright 2022-2025 Red Hat, Inc. + + 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. + + + + This protocol extension delivers the metadata required to define alpha mode, + the color model, sub-sampling and quantization range used when interpreting + buffer contents. The main use case is defining how the YCbCr family of pixel + formats convert to RGB. + + Note that this protocol does not define the colorimetry of the resulting RGB + channels / tristimulus values. Without the help of other extensions the + resulting colorimetry is therefore implementation defined. + + If this extension is not used, the color representation used is compositor + implementation defined. + + Recommendation ITU-T H.273 + "Coding-independent code points for video signal type identification" + shall be referred to as simply H.273 here. + + + + + A singleton global interface used for getting color representation + extensions for wl_surface. The extension interfaces allow setting the + color representation of surfaces. + + Compositors should never remove this global. + + + + + + + + + + Destroy the wp_color_representation_manager_v1 object. This does not + affect any other objects in any way. + + + + + + + If a wp_color_representation_surface_v1 object already exists for the + given wl_surface, the protocol error surface_exists is raised. + + This creates a new color wp_color_representation_surface_v1 object for + the given wl_surface. + + See the wp_color_representation_surface_v1 interface for more details. + + + + + + + + When this object is created, it shall immediately send this event once + for each alpha mode the compositor supports. + + For the definition of the supported values, see the + wp_color_representation_surface_v1::alpha_mode enum. + + + + + + + When this object is created, it shall immediately send this event once + for each matrix coefficient and color range combination the compositor + supports. + + For the definition of the supported values, see the + wp_color_representation_surface_v1::coefficients and + wp_color_representation_surface_v1::range enums. + + + + + + + + This event is sent when all supported features have been sent. + + + + + + + A wp_color_representation_surface_v1 allows the client to set the color + representation metadata of a surface. + + By default, a surface does not have any color representation metadata set. + The reconstruction of R, G, B signals on such surfaces is compositor + implementation defined. The alpha mode is assumed to be + premultiplied_electrical when the alpha mode is unset. + + If the wl_surface associated with the wp_color_representation_surface_v1 + is destroyed, the wp_color_representation_surface_v1 object becomes inert. + + + + + + + + + + + + + Destroy the wp_color_representation_surface_v1 object. + + Destroying this object unsets all the color representation metadata from + the surface. See the wp_color_representation_surface_v1 interface + description for how a compositor handles a surface without color + representation metadata. Unsetting is double-buffered state, see + wl_surface.commit. + + + + + + Specifies how the alpha channel affects the color channels. + + + + Electrical color channel values (after transfer function encoding) + are already multiplied with the alpha channel value. + + + + + Optical color channel values (before transfer function encoding) + are already multiplied with the alpha channel value. + + + + + Alpha channel has not been pre-multiplied into color channels. + + + + + + + Named matrix coefficients used to encode well-known sets of + coefficients. H.273 is the authority, when it comes to the exact values + of coefficients and authoritative specifications, where an equivalent + code point exists. + + A value of 0 is invalid and will never be present in the list of enums. + + Descriptions do list the specifications for convenience. + + + + Coefficients as defined by + - IEC 61966-2-1 sRGB + - SMPTE ST 428-1 (2019) + + Equivalent to H.273 MatrixCoefficients code point 0. + Compatible with pixel formats of the RGB family. + + + + + Coefficients as defined by + - Rec. ITU-R BT.709-6 + - Rec. ITU-R BT.1361-0 conventional colour gamut system (historical) + - Rec. ITU-R BT.1361-0 conventional colour gamut system and extended + colour gamut system (historical) + - IEC 61966-2-4 xvYCC709 + - SMPTE RP 177 (1993) Annex B + + Equivalent to H.273 MatrixCoefficients code point 1. + Compatible with pixel formats of the YCbCr family. + + + + + Coefficients as defined by + - United States Federal Communications Commission (2003) Title 47 + Code of Federal Regulations 73.682 (a) (20) + + Equivalent to H.273 MatrixCoefficients code point 4. + Compatible with pixel formats of the YCbCr family. + + + + + Coefficients as defined by + - Rec. ITU-R BT.470-6 System B, G (historical) + - Rec. ITU-R BT.601-7 625 + - Rec. ITU-R BT.601-7 525 + - Rec. ITU-R BT.1358-0 625 (historical) + - Rec. ITU-R BT.1358-1 525 or 625 (historical) + - Rec. ITU-R BT.1700-0 625 PAL and 625 SECAM + - Rec. ITU-R BT.1700-0 NTSC + - IEC 61966-2-1 sYCC + - IEC 61966-2-4 xvYCC601 + - SMPTE ST 170 (2004) + + Equivalent to H.273 MatrixCoefficients code point 5, 6. + Compatible with pixel formats of the YCbCr family. + + + + + Coefficients as defined by + - RSMPTE ST 240 (1999) + + Equivalent to H.273 MatrixCoefficients code point 7. + Compatible with pixel formats of the YCbCr family. + + + + + Coefficients as defined by + - Rec. ITU-R BT.2020-2 (non-constant luminance) + - Rec. ITU-R BT.2100-2 Y′CbCr + + Equivalent to H.273 MatrixCoefficients code point 9. + Compatible with pixel formats of the YCbCr family. + + + + + Coefficients as defined by + - Rec. ITU-R BT.2020-2 (constant luminance) + + Equivalent to H.273 MatrixCoefficients code point 10. + Compatible with pixel formats of the YCbCr family. + + + + + Coefficients as defined by + - Rec. ITU-R BT.2100-2 ICTCP + + Equivalent to H.273 MatrixCoefficients code point 14. + Compatible with pixel formats of the YCbCr family. + + + + + + + Possible color range values. + + A value of 0 is invalid and will never be present in the list of enums. + + + + + + + + Chroma sample location as defined by H.273 Chroma420SampleLocType. + + A value of 0 is invalid and will never be present in the list of enums. + + The descriptions list the matching Vulkan VkChromaLocation combinations + for convenience. + + + + Corresponding to VkChromaLocations: + - xChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN + - yChromaOffset: VK_CHROMA_LOCATION_MIDPOINT + + Equivalent to H.273 Chroma420SampleLocType 0. + + + + + Corresponding to VkChromaLocations: + - xChromaOffset: VK_CHROMA_LOCATION_MIDPOINT + - yChromaOffset: VK_CHROMA_LOCATION_MIDPOINT + + Equivalent to H.273 Chroma420SampleLocType 1. + + + + + Corresponding to VkChromaLocations: + - xChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN + - yChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN + + Equivalent to H.273 Chroma420SampleLocType 2. + + + + + Corresponding to VkChromaLocations: + - xChromaOffset: VK_CHROMA_LOCATION_MIDPOINT + - yChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN + + Equivalent to H.273 Chroma420SampleLocType 3. + + + + + Equivalent to H.273 Chroma420SampleLocType 4. + + + + + Equivalent to H.273 Chroma420SampleLocType 5. + + + + + + + If this protocol object is inert, the protocol error inert is raised. + + Assuming an alpha channel exists, it is always linear. The alpha mode + determines whether and how the color channels include pre-multiplied + alpha. Using straight alpha might have performance benefits. + + Only alpha modes advertised by the compositor are allowed to be used as + argument for this request. The "alpha_mode" protocol error is raised + otherwise. + + Alpha mode is double buffered, see wl_surface.commit. + + + + + + + If this protocol object is inert, the protocol error inert is raised. + + Set the matrix coefficients and video range which defines the formula + and the related constants used to derive red, green and blue signals. + Usually coefficients correspond to MatrixCoefficients code points in + H.273. + + Only combinations advertised by the compositor are allowed to be used as + argument for this request. The "coefficients" protocol error is raised + otherwise. + + A call to wl_surface.commit verifies that the pixel format and the + coefficients-range combination in the committed surface contents are + compatible, if contents exist. The "pixel_format" protocol error is + raised otherwise. + + A pixel format is compatible with the coefficients-range combination if + the related equations and conventions as defined in H.273 can produce + the color channels (RGB or YCbCr) of the pixel format. + + For the definition of the supported combination, see the + wp_color_representation_surface_v1::coefficients and + wp_color_representation_surface_v1::range enums. + + The coefficients-range combination is double-buffered, see + wl_surface.commit. + + + + + + + + If this protocol object is inert, the protocol error inert is raised. + + Set the chroma location type which defines the position of downsampled + chroma samples, corresponding to Chroma420SampleLocType code points in + H.273. + + A call to wl_surface.commit verifies that the pixel format and chroma + location type in the committed surface contents are compatible, if + contents exist. The "pixel_format" protocol error is raised otherwise. + + For the definition of the supported chroma location types, see the + wp_color_representation_surface_v1::chroma_location enum. + + The chroma location type is double-buffered, see wl_surface.commit. + + + + + diff --git a/staging/color-representation/notes.rst b/staging/color-representation/notes.rst new file mode 100644 index 0000000..cf42d20 --- /dev/null +++ b/staging/color-representation/notes.rst @@ -0,0 +1,79 @@ +.. Copyright 2022 Red Hat, Inc. + +.. contents:: + +Rec ITU-T H.273 +=============== + +Rec ITU-T H.273 (short H.273) is a Recommendation from the International +Telecommunication Union (ITU) with the title "Coding-independent code points for +video signal type identification". All published versions can be found at +https://www.itu.int/rec/T-REC-H.273/en. + +For a quick introduction to Rec ITU-T H.273 see +https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/cicp_h273.md. + +Code point and pixel format compatibility +========================================= + +Certain color representation metadata requires the selected code point to be +compatible with the buffer's pixel format. Which code points are compatible with +which pixel formats depends on the type of metadata. + +All ``Chroma420SampleLocType`` chroma location code points are compatible with +4:2:0 subsampled pixel formats. Using a pixel format which is not 4:2:0 +subsampled in a commit where a ``Chroma420SampleLocType`` code point is set +results in a protocol error. Clients can unset all code points again by +destroying the wp_color_representation_surface_v1, when they switch to such +formats. + +The matrix coefficients' code point and pixel format compatibility is harder to +determine and depends on the specific code point. + +The ``MatrixCoefficients`` code points are defined by "Rec ITU-T H.273 +Coding-independent code points for video signal type identification". This +document further defines equations which describe how a tristimulus value can be +transformed. Which equations can be applied depends on which +``MatrixCoefficients`` code point is selected and if the ``VideoFullRangeFlag`` +is set or not. By applying the applicable equations on a tristimulus value one +or more color encodings can be inferred. This color encoding has three channels +and each of those channels must map to the pixel format of the surface's buffer. +In Rec ITU-T H.273 (07/21) those channels are either R, G and B or Y, Cb and Cr. + +Equations numbers used in the examples below are taken from Rec ITU-T H.273 +(07/21) and might change in future versions. + +For example code point 0: equations 11-13 transform the tristimulus values E\ +:sub:`R`, E\ :sub:`G`, E\ :sub:`B` to a non-linear encoding E'\ :sub:`R`, E'\ +:sub:`G`, E'\ :sub:`B`. Those can be transformed to an RGB encoding with +equations 20-22 (if the ``VideoFullRangeFlag`` is not set) or 26-28 (if the +``VideoFullRangeFlag`` is set). A YCbCr encoding can be inferred from the RGB +encoding with equations 41-43. + +Therefore the code point 0 is compatible only with pixel formats which contain +the RGB or YCbCr color channels. The pixel formats may additionally carry unused +bits, alpha or other channels. + +For example code point 1: apply equations 11-13, 38-40 and either 23-25 or 29-31 +(depending on the ``VideoFullRangeFlag``) to arrive at the YCbCr encoding. An +RGB encoding cannot be inferred from the applicable equations. + +Therefore code point 1 is is compatible only with pixel formats which contain +the YCbCr color channels. + +MatrixCoefficients usage +======================== + +Note that the ``MatrixCoefficients`` equations as defined by Rec ITU-T H.273 +describe how the client transforms the tristimulus values to an encoding which +ends up in the buffer it sends to the compositor. Compositors will use the +inverse steps, including the transfer characteristics which are not defined by +this protocol to convert the encoding back to tristimulus values with color +primaries which are also not defined by this protocol. + +Some ``MatrixCoefficients`` code points require applying formulas or infering +constants from the transfer characteristics or color primaries of the image. +Compositors should not advertise support for such code points if the client +can't communicate the transfer characteristics and color primaries to the +compositor. Communicating those when needed is left for other Wayland extensions +to be used in conjunction with color-representation. \ No newline at end of file