Skip to content

wp_color_manager_v1¤

wayland.wp_color_manager_v1 ¤

Color manager singleton

A singleton 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.

Compositors should never remove this global.

Methods:

error ¤

render_intent ¤

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.

feature ¤

Compositor supported features

  • icc_v2_v4 –
    `create_icc_creator` request
  • parametric –
    `create_parametric_creator` request
  • set_primaries –
    Parametric `set_primaries` request
  • set_tf_power –
    Parametric `set_tf_power` request
  • set_luminances –
    Parametric `set_luminances` request
  • set_mastering_display_primaries –
    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.
  • extended_target_volume –
    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.
  • windows_scrgb –
    `create_windows_scrgb` request

primaries ¤

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.

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

Descriptions do list the specifications for convenience.

  • srgb –
    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.
  • pal_m –
    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.
  • pal –
    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.
  • ntsc –
    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.
  • generic_film –
    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.
  • bt2020 –
    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.
  • cie1931_xyz –
    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.
  • dci_p3 –
    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.
  • display_p3 –
    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.
  • adobe_rgb –
    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).

transfer_function ¤

Named transfer functions

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.

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

Descriptions do list the specifications for convenience.

  • bt1886 –
    Bt.1886 display transfer characteristic Rec. ITU-R BT.1886 is the display transfer characteristic assumed by - 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² - primary color volume maximum: 100 cd/m² - reference white: 100 cd/m²
  • gamma22 –
    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. Note: an sRGB display (IEC 61966-2-1) uses this transfer function.
  • gamma28 –
    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.
  • st240 –
    Smpte st 240 transfer function Transfer characteristics as defined by - SMPTE ST 240 (1999) Equivalent to H.273 TransferCharacteristics code point 7.
  • ext_linear –
    Extended linear transfer function 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.
  • log_100 –
    Logarithmic 100:1 transfer function Logarithmic transfer characteristic (100:1 range). Equivalent to H.273 TransferCharacteristics code point 9.
  • log_316 –
    Logarithmic (100*sqrt(10) : 1) transfer function Logarithmic transfer characteristic (100 * Sqrt(10) : 1 range). Equivalent to H.273 TransferCharacteristics code point 10.
  • xvycc –
    Iec 61966-2-4 transfer function Transfer characteristics as defined by - IEC 61966-2-4 Equivalent to H.273 TransferCharacteristics code point 11.
  • srgb –
    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. Note: This is not appropriate for describing sRGB material. sRGB material is intended to be viewed on an sRGB display, and that is described by gamma22.
  • ext_srgb –
    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.
  • st2084_pq –
    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. This TF implies these default luminances - primary color volume minimum: 0.005 cd/m² - primary color volume maximum: 10000 cd/m² - reference white: 203 cd/m² The difference between the primary color volume minimum and maximum must be approximately 10000 cd/m² as that is the swing of the EOTF defined by ST 2084 and BT.2100. The default value for the reference white is a protocol addition: it is suggested by Report ITU-R BT.2408-7 and is not part of ST 2084 or BT.2100.
  • st428 –
    Smpte st 428 transfer function Transfer characteristics as defined by - SMPTE ST 428-1 (2019) Equivalent to H.273 TransferCharacteristics code point 17.
  • hlg –
    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. This TF implies these default luminances - primary color volume minimum: 0.005 cd/m² - primary color volume maximum: 1000 cd/m² - reference white: 203 cd/m² HLG is a relative display-referred signal with a specified non-linear mapping to the display peak luminance (the HLG OOTF). All absolute luminance values used here for HLG assume a 1000 cd/m² peak display. The default value for the reference white is a protocol addition: it is suggested by Report ITU-R BT.2408-7 and is not part of ARIB STD-B67 or BT.2100.

events

supported_intent ¤

supported_intent(render_intent: render_intent) -> None

Supported rendering intent

When this object is created, it shall immediately send this event once for each rendering intent the compositor supports.

Parameters:

supported_feature ¤

supported_feature(feature: feature) -> None

Supported features

When this object is created, it shall immediately send this event once for each compositor supported feature listed in the enumeration.

Parameters:

supported_tf_named ¤

supported_tf_named(tf: transfer_function) -> None

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.

Parameters:

supported_primaries_named ¤

supported_primaries_named(primaries: primaries) -> None

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.

Parameters:

done ¤

done() -> None

All features have been sent

This event is sent when all supported rendering intents, features, transfer functions and named primaries have been sent.

destroy ¤

destroy() -> None

Destroy the color manager

Destroy the wp_color_manager_v1 object. This does not affect any other objects in any way.

get_output ¤

get_output(output: wl_output) -> wp_color_management_output_v1

Create a color management interface for a wl_output

This creates a new wp_color_management_output_v1 object for the given wl_output.

See the wp_color_management_output_v1 interface for more details.

Returns:

get_surface ¤

get_surface(surface: wl_surface) -> wp_color_management_surface_v1

Create a color management interface for a wl_surface

If a wp_color_management_surface_v1 object already exists for the given wl_surface, the protocol error surface_exists is raised.

This creates a new color wp_color_management_surface_v1 object for the given wl_surface.

See the wp_color_management_surface_v1 interface for more details.

Returns:

get_surface_feedback ¤

get_surface_feedback(surface: wl_surface) -> wp_color_management_surface_feedback_v1

Create a color management feedback interface

This creates a new color wp_color_management_surface_feedback_v1 object for the given wl_surface.

See the wp_color_management_surface_feedback_v1 interface for more details.

Returns:

create_icc_creator ¤

create_icc_creator() -> wp_image_description_creator_icc_v1

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 wp_image_description_v1 object.

This request can be used when the compositor advertises wp_color_manager_v1.feature.icc_v2_v4. Otherwise this request raises the protocol error unsupported_feature.

Returns:

create_parametric_creator ¤

create_parametric_creator() -> wp_image_description_creator_params_v1

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 wp_image_description_v1 object.

This request can be used when the compositor advertises wp_color_manager_v1.feature.parametric. Otherwise this request raises the protocol error unsupported_feature.

Returns:

create_windows_scrgb ¤

create_windows_scrgb() -> wp_image_description_v1

Create windows-scrgb image description object

This creates a pre-defined image description for the so-called Windows-scRGB stimulus encoding. This comes from the Windows 10 handling of its own definition of an scRGB color space for an HDR screen driven in BT.2100/PQ signalling mode.

Windows-scRGB uses sRGB (BT.709) color primaries and white point. The transfer characteristic is extended linear.

The nominal color channel value range is extended, meaning it includes negative and greater than 1.0 values. Negative values are used to escape the sRGB color gamut boundaries. To make use of the extended range, the client needs to use a pixel format that can represent those values, e.g. floating-point 16 bits per channel.

Nominal color value R=G=B=0.0 corresponds to BT.2100/PQ system 0 cd/m², and R=G=B=1.0 corresponds to BT.2100/PQ system 80 cd/m². The maximum is R=G=B=125.0 corresponding to 10k cd/m².

Windows-scRGB is displayed by Windows 10 by converting it to BT.2100/PQ, maintaining the CIE 1931 chromaticity and mapping the luminance as above. No adjustment is made to the signal to account for the viewing conditions.

The reference white level of Windows-scRGB is unknown. If a reference white level must be assumed for compositor processing, it should be R=G=B=2.5375 corresponding to 203 cd/m² of Report ITU-R BT.2408-7.

The target color volume of Windows-scRGB is unknown. The color gamut may be anything between sRGB and BT.2100.

Note: EGL_EXT_gl_colorspace_scrgb_linear definition differs from Windows-scRGB by using R=G=B=1.0 as the reference white level, while Windows-scRGB reference white level is unknown or varies. However, it seems probable that Windows implements both EGL_EXT_gl_colorspace_scrgb_linear and Vulkan VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT as Windows-scRGB.

This request can be used when the compositor advertises wp_color_manager_v1.feature.windows_scrgb. 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.

Returns:

on_supported_intent ¤

on_supported_intent(render_intent: render_intent) -> None

Supported rendering intent.

Override to handle wayland.wp_color_manager_v1.events.supported_intent.

on_supported_feature ¤

on_supported_feature(feature: feature) -> None

Supported features.

Override to handle wayland.wp_color_manager_v1.events.supported_feature.

on_supported_tf_named ¤

on_supported_tf_named(tf: transfer_function) -> None

Supported named transfer characteristic.

Override to handle wayland.wp_color_manager_v1.events.supported_tf_named.

on_supported_primaries_named ¤

on_supported_primaries_named(primaries: primaries) -> None

Supported named primaries.

Override to handle wayland.wp_color_manager_v1.events.supported_primaries_named.

on_done ¤

on_done() -> None

All features have been sent.

Override to handle wayland.wp_color_manager_v1.events.done.