Skip to content

wp_color_representation_surface_v1¤

wayland.wp_color_representation_surface_v1 ¤

Color representation extension to a surface

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.

Methods:

error ¤

Protocol errors

alpha_mode ¤

Alpha mode

Specifies how the alpha channel affects the color channels.

  • premultiplied_electrical –
    Premultiplied alpha in electrical values Electrical color channel values (after transfer function encoding) are already multiplied with the alpha channel value.
  • premultiplied_optical –
    Premultiplied alpha in optical values Optical color channel values (before transfer function encoding) are already multiplied with the alpha channel value.
  • straight –
    Straight alpha Alpha channel has not been pre-multiplied into color channels.

coefficients ¤

Named coefficients

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.

  • identity –
    The identity matrix 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.
  • bt709 –
    Bt.709 matrix coefficients 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.
  • fcc –
    Fcc matrix coefficients 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.
  • bt601 –
    Bt.601-7 matrix coefficients 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.
  • smpte240 –
    Smpte st 240 matrix coefficients Coefficients as defined by - SMPTE ST 240 (1999) Equivalent to H.273 MatrixCoefficients code point 7. Compatible with pixel formats of the YCbCr family.
  • bt2020 –
    Bt.2020 and bt.2100 ycbcr matrix coefficients 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.
  • bt2020_cl –
    Bt.2020 matrix coefficients for constant luminance 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.
  • ictcp –
    Bt.2100 ictcp matrix coefficients 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.

range ¤

Color range values

Possible color range values.

A value of 0 is invalid and will never be present in the list of enums.

chroma_location ¤

Chroma sample location for 4:2:0 ycbcr

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.

  • type_0 –
    Horizontal offset of 0, vertical offset of 0.5 Corresponding to VkChromaLocations: - xChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN - yChromaOffset: VK_CHROMA_LOCATION_MIDPOINT Equivalent to H.273 Chroma420SampleLocType 0.
  • type_1 –
    Horizontal offset of 0.5, vertical offset of 0.5 Corresponding to VkChromaLocations: - xChromaOffset: VK_CHROMA_LOCATION_MIDPOINT - yChromaOffset: VK_CHROMA_LOCATION_MIDPOINT Equivalent to H.273 Chroma420SampleLocType 1.
  • type_2 –
    Horizontal offset of 0, vertical offset of 0 Corresponding to VkChromaLocations: - xChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN - yChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN Equivalent to H.273 Chroma420SampleLocType 2.
  • type_3 –
    Horizontal offset of 0.5, vertical offset of 0 Corresponding to VkChromaLocations: - xChromaOffset: VK_CHROMA_LOCATION_MIDPOINT - yChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN Equivalent to H.273 Chroma420SampleLocType 3.
  • type_4 –
    Horizontal offset of 0, vertical offset of 1 Equivalent to H.273 Chroma420SampleLocType 4.
  • type_5 –
    Horizontal offset of 0.5, vertical offset of 1 Equivalent to H.273 Chroma420SampleLocType 5.

destroy ¤

destroy() -> None

Destroy the color representation

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.

set_alpha_mode ¤

set_alpha_mode(alpha_mode: alpha_mode) -> None

Set the surface alpha mode

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.

Parameters:

set_coefficients_and_range ¤

set_coefficients_and_range(coefficients: coefficients, range: range) -> None

Set the matrix coefficients and range

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.

Parameters:

set_chroma_location ¤

set_chroma_location(chroma_location: chroma_location) -> None

Set the chroma location

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.

Parameters: