From f3e14e400713225452ab96f446d18fa4d2e92795 Mon Sep 17 00:00:00 2001 From: Pekka Paalanen Date: Tue, 2 Sep 2025 14:07:43 +0300 Subject: [PATCH] staging/color-management: clarify the displayness There have been complaints that it was not clear everything is display-referred: https://gitlab.freedesktop.org/wayland/wayland-protocols/-/merge_requests/442#note_3079533 The section in Wayland documentation makes it very clear, so link to it. Mention the attention to the display explicitly. Signed-off-by: Pekka Paalanen --- .../color-management/color-management-v1.xml | 35 ++++++++++++------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/staging/color-management/color-management-v1.xml b/staging/color-management/color-management-v1.xml index 679c4a0..2958a19 100644 --- a/staging/color-management/color-management-v1.xml +++ b/staging/color-management/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,12 +48,14 @@ 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. The color-and-hdr repository (https://gitlab.freedesktop.org/pq/color-and-hdr) contains @@ -241,7 +248,7 @@ Named transfer functions used to represent well-known transfer - characteristics. + characteristics of displays. A value of 0 is invalid and will never be present in the list of enums. @@ -1278,11 +1285,13 @@ - 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