Wayland color management protocol proposal

[John Kåre Alsaker]

Here is my current color management protocol for Wayland clients. The
basic idea is that the compositor sends two color spaces to the
clients. A compositing color space which the compositor prefers since
it would require no conversions. A full-screen color space which the
compositor can be able to scan out from. The full-screen color space
is intended to used by games which are able to do color conversions as
part of their post-processing. It's also possible it could be used by
video players.

Different rendering intents and more advanced color spaces have not
explicitly been considered here, but I hope the use of ICC profiles
will cover these.
Calibration tools will require explicit privileges in order to do
their job. Using the full-screen color space won't be enough since
video card gamma correction can apply to it. I also wonder if we can
just remove the VCGT tag from the ICC profiles to indicate that the
client doesn't have to correct for that, but I'm not sure that anyone
would use the tag anyway.

<protocol name="cms">
  <interface name="wl_cms_factory" version="1">
    <request name="destroy" type="destructor"/>

    <enum name="error">
      <entry name="bad_surface" value="0"
             summary="the given wl_surface is invalid"/>
      <entry name="bad_output" value="1"
             summary="the given wl_output is invalid"/>
    </enum>

    <request name="get_cms_surface">
      <arg name="id" type="new_id" interface="wl_cms_surface"
           summary="the new cms-surface object id"/>
      <arg name="surface" type="object" interface="wl_surface"
           summary="the surface to be turned into a cms-surface"/>
    </request>
	
    <request name="get_cms_output">
      <arg name="id" type="new_id" interface="wl_cms_output"
           summary="the new cms-output object id"/>
      <arg name="surface" type="object" interface="wl_output"
           summary="the output to be turned into a cms-output"/>
    </request>
	
    <request name="create_rgb_color_space">
      <description summary="create a RGB color space">
        Creates a new color space from a RGB model.
        If the compositor is unable to use the RGB model, an undefined
color space will be created instead.
      </description>
      <arg name="id" type="new_id" interface="wl_color_space"
           summary="the new color space object id"/>
      <arg name="gamma" type="int"/>
      <arg name="gamut" type="int"/>
      <arg name="parameters" type="array"/>
    </request>
	
    <request name="create_profile_color_space">
      <description summary="create color space from profile">
        Creates a new color space from a profile.
        If the compositor is unable to use the profile, an undefined
color space will be created instead.
      </description>
      <arg name="id" type="new_id" interface="wl_color_space"
           summary="the new color space object id"/>
      <arg name="mime_type" type="string"/>
      <arg name="fd" type="fd"/>
    </request>
  </interface>

  <interface name="wl_cms_output" version="1">
    <request name="destroy" type="destructor"/>
	
    <event name="compositing_color_space">
      <description summary="update the output's compositing color space">
        This event is send when wl_cms_output is created and when the
compositor's compositing color space for the output changes.

        This is the color space the compositor uses internally when
compositing surfaces on this output. Clients should try to render
        content in this space as it's the most efficient when surfaces
are not fullscreen and compositing is required.
        However surfaces using this color space may not be able to be
scanned out.

        If the client doesn't intend to use the passed color space, it
must destroy it when receiving this event.
      </description>
      <arg name="color_space" type="new_id" interface="wl_color_space"/>
    </event>

    <event name="fullscreen_color_space">
      <description summary="update the output's fullscreen color space">
        This event is send when wl_cms_output is created and when the
compositor's fullscreen color space for the output changes.

        This is the native color space of the output where the
compositor don't have to use any conversions to display it.
        The compositor may not be able to do compositing in this color
space without expensive conversions.

        If the client doesn't intend to use the passed color space, it
must destroy it when receiving this event.
      </description>
      <arg name="color_space" type="new_id" interface="wl_color_space"/>
    </event>
  </interface>

  <interface name="wl_cms_surface" version="1">
    <request name="destroy" type="destructor"/>
	
    <request name="set_color_space">
      <description summary="set the color space of a surface">
        This request sets the color space of a wl_surface. If
color_space is NULL or undefined, the default color space will be used
instead.
        It's state is buffered so triggering wl_surface.commit is
required for it to take effect.
      </description>
      <arg name="color_space" type="object" interface="wl_color_space"
 allow-null="true"/>
    </request>
  </interface>

  <interface name="wl_color_space" version="1">
    <description summary="a color space">
      This is an object representing a single color space.
	
      When a wl_color_space is created, one of the events 'rgb_model',
'profile' or 'undefined' will be sent describing the color space.
    </description>
	
    <request name="destroy" type="destructor">
      <description summary="destroy the color space">
        Destroys the color space.
      </description>
    </request>

    <enum name="rgb_gamma">
      <description summary="the gamma function of a RGB color space"/>
      <entry name="srgb" value="0" summary="the sRGB gamma function"/>
      <entry name="srgb_encoded_alpha" value="1">
        <description summary="the sRGB gamma function with alpha
multiplied in before">
         The sRGB gamma function with alpha multiplied in before when
         using premultiplied alpha: to_srgb_gamma(color * alpha).
        </description>
      </entry>
      <entry name="linear" value="2"/>
    </enum>

    <enum name="rgb_gamut">
      <description summary="the gamut of a RGB color space"/>
      <entry name="srgb" value="0" summary="the sRGB gamut"/>
      <entry name="custom" value="3">
        <description summary="custom gamut">
          A custom gamut is used as specified by the parameters argument.
        </description>
      </entry>
    </enum>

    <event name="rgb_model">
      <description summary="information about the RGB color space model">
        Information about the RGB color space model.
		
        The content of 'parameters' is the CIE 1931 XYZ coordiantes of
the red, green and blue primaries
        followed by the white point. These are stored as an array of
single precision IEEE floats.
        'parameters' is empty unless gamut is custom.
      </description>
      <arg name="gamma" type="int"/>
      <arg name="gamut" type="int"/>
      <arg name="parameters" type="array"/>
    </event>

    <event name="profile">
      <description summary="profile details">
        This color space is defined by a color profile.
      </description>
      <arg name="mime_type" type="string"/>
      <arg name="fd" type="fd"/>
    </event>
	
    <event name="undefined">
      <description summary="undefined color space">
        The color space is undefined.
      </description>
    </event>
  </interface>
</protocol>