[RFC 0/1] Color manager calibration protocol v1

Sebastian Wick sebastian at sebastianwick.net
Mon Apr 15 18:30:13 UTC 2019

On 2019-04-14 12:57, Erwin Burema wrote:
> Without a way to calibrate/profile screens an color management
> protocol looses a lot of its value. So to add this missing feature I
> wrote the following protocol.
> The idea is that the calibration/profiling SW only sets the RGB
> triplet and then the compositor is responsible to draw a rectanglular
> region on the selected output screen, since not all calibration tools
> will be at the center of the screen a user should be able to modify
> the placement of this rectanglular region. Unless specified the
> monitor profile (if any) should not be applied but the GPU curve
> should, currently to set a new curve the calibration tool should
> generate a new ICC profile with the wanted curve in the VCGT tag (I am
> not sure if this is the best option but would make the most universal
> one). In the end after profiling the last uploaded ICC could then be
> saved (although a compositor is not required to honor the request in
> that case it should send the not saved error). If the compositor
> doesn't save or the connection with this protocol is broken the
> compositor should restore previous settings.
> Currently no support to calibrate HDR screens since this will require
> direct access (no tonemapping or color correction should happen in the
> screen, with the potential exception if it is possible to upload
> custom LUTs to the screen), this will require something like the
> FREESYN2_GAMMA22 display mode as described here:
> https://gpuopen.com/using-amd-freesync-2-hdr-color-spaces/ if this is
> not available a HDR screen should be treated as if it is a rec2020+PQ
> or HLG since it will do its own compositing+color managing (which
> might or might not be correct)
> Erwin Burema (1):
>   Add color manager calibration protocol v1
>  .../cm_wayland_calibration.xml                | 106 ++++++++++++++++++
>  1 file changed, 106 insertions(+)
>  create mode 100644
> unstable/color-manager-calibration/cm_wayland_calibration.xml

The requirement to let the user position the patch makes me think that
using a normal surface in a special mode makes more sense. Maybe
something like this would work:

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="color_measure_unstable_v1">

   <description summary="color calibration and profiling">

   <interface name="zwp_color_measure_v1" version="1">
     <description summary="">

     <enum name="measure_mode">
       <description summary="">
       <entry name="standard" value="0" summary=""/>
       <entry name="passthrough" value="1" summary=""/>

     <request name="get_color_measurement_surface">
       <description summary="">
       <arg name="id" type="new_id" 
       <arg name="surface" type="object" interface="wl_surface"/>
       <arg name="output" type="object" interface="wl_output"/>
       <arg name="mode" type="uint" enum="measure_mode" 

     <request name="destroy" type="destructor">
       <description summary="destroy the color measure">

   <interface name="zwp_color_measure_surface_v1" version="1">
     <description summary="">
	The underlying surface has a state which indicates if it is shown on 
	output without further manipulation.

	In particular if the surface is in the state valid with mode standard 
	compositor guarantees that only the color correction pipeline and no
	"special" effects are applied to the surface.

	In the state valid with mode passthrough the color values of the 
surface are
	gauranteed to reach the output as is (e.g. no color correction and no 
	LUT gets applied).

	If the state is invalid there is no guarantee how the color values are
	transformed before reaching the output.

     <enum name="state">
       <description summary="">
       <entry name="valid" value="0" summary=""/>
       <entry name="invalid" value="1" summary=""/>

     <request name="sync">

     <event name="done">

     <event name="state_changed">
       <arg name="state" type="uint" enum="state"/>

     <request name="destroy" type="destructor">
       <description summary="destroy the color measure surface">


I'd imagine the client to do something like this:

1. create a zwp_color_measure_surface_v1 for the surface and the output
    to measure in the passthrough mode
2. tell the user to position the surface correctly and wait for the
    state to be valid (for example in gnome shell the state would be
    invalid when the surface is shown in expose or not shown on the 
    at all)
3. calibrate by filling the surface and applying the "vcgt" in software
4. profile
5. if the state changes to invalid in between go to 2
6. create the ICC profile and load it to the compositor via colord
7. destroy the interface, create a new one in the standard mode
8. wait for the state to be valid (as before)
9. measure the colors and check if the profile works as intended
10. if the state changes to invalid in between go to 8

More information about the wayland-devel mailing list