[PATCH 1/6] Add cms protocol

[Bryce Harrington]

On Mon, Oct 13, 2014 at 07:40:46PM +0200, Niels Ole Salscheider wrote:
> The cms protocol allows to attach an ICC profile to a surface. It also tells
> the client about the blending color space and the color spaces of all outputs.
> 
> Signed-off-by: Niels Ole Salscheider <niels_ole at salscheider-online.de>
> ---
>  Makefile.am      |  15 +++++--
>  protocol/cms.xml | 132 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 143 insertions(+), 4 deletions(-)
>  create mode 100644 protocol/cms.xml
> 
> diff --git a/Makefile.am b/Makefile.am
> index 10be920..3af3b46 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -81,7 +81,9 @@ nodist_weston_SOURCES =					\
>  	protocol/presentation_timing-protocol.c		\
>  	protocol/presentation_timing-server-protocol.h	\
>  	protocol/scaler-protocol.c			\
> -	protocol/scaler-server-protocol.h
> +	protocol/scaler-server-protocol.h		\
> +	protocol/cms-protocol.c				\
> +	protocol/cms-server-protocol.h
>  
>  BUILT_SOURCES += $(nodist_weston_SOURCES)
>  
> @@ -458,7 +460,9 @@ nodist_libtoytoolkit_la_SOURCES =			\
>  	protocol/presentation_timing-protocol.c		\
>  	protocol/presentation_timing-client-protocol.h	\
>  	protocol/xdg-shell-protocol.c			\
> -	protocol/xdg-shell-client-protocol.h
> +	protocol/xdg-shell-client-protocol.h		\
> +	protocol/cms-protocol.c				\
> +	protocol/cms-client-protocol.h
>  
>  BUILT_SOURCES += $(nodist_libtoytoolkit_la_SOURCES)
>  
> @@ -649,7 +653,9 @@ BUILT_SOURCES +=					\
>  	protocol/fullscreen-shell-protocol.c		\
>  	protocol/fullscreen-shell-client-protocol.h	\
>  	protocol/xdg-shell-protocol.c			\
> -	protocol/xdg-shell-client-protocol.h
> +	protocol/xdg-shell-client-protocol.h		\
> +	protocol/cms-protocol.c				\
> +	protocol/cms-client-protocol.h
>  
>  
>  westondatadir = $(datadir)/weston
> @@ -1011,7 +1017,8 @@ EXTRA_DIST +=					\
>  	protocol/xdg-shell.xml			\
>  	protocol/fullscreen-shell.xml		\
>  	protocol/presentation_timing.xml	\
> -	protocol/scaler.xml
> +	protocol/scaler.xml			\
> +	protocol/cms.xml
>  
>  man_MANS = weston.1 weston.ini.5
>  
> diff --git a/protocol/cms.xml b/protocol/cms.xml
> new file mode 100644
> index 0000000..34c1b16
> --- /dev/null
> +++ b/protocol/cms.xml
> @@ -0,0 +1,132 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<protocol name="cms">
> +
> +  <copyright>
> +    Copyright © 2014 Niels Ole Salscheider
> +
> +    Permission to use, copy, modify, distribute, and sell this
> +    software and its documentation for any purpose is hereby granted
> +    without fee, provided that the above copyright notice appear in
> +    all copies and that both that copyright notice and this permission
> +    notice appear in supporting documentation, and that the name of
> +    the copyright holders not be used in advertising or publicity
> +    pertaining to distribution of the software without specific,
> +    written prior permission.  The copyright holders make no
> +    representations about the suitability of this software for any
> +    purpose.  It is provided "as is" without express or implied
> +    warranty.
> +
> +    THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
> +    SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
> +    FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
> +    SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
> +    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
> +    AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
> +    ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
> +    THIS SOFTWARE.
> +  </copyright>
> +
> +  <interface name="wl_cms" version="1">
> +    <description summary="allows to attach a color space to a wl_surface">

Should be:

"allows attaching a color space to a wl_surface"

or maybe

"allows attachment of a color space to a wl_surface"

> +      This interface allows to attach a color space to a wl_surface. This is

ditto

> +      used by the compositor to display the colors correctly. For this, the
> +      compositor converts any attached surfaces to the blending color space
> +      before the blending operations. After blending, the output surface is
> +      converted to the color space of the output device.
> +      This interface also provides requests for the sRGB and the blending color
> +      space. It further allows to create a color space from an ICC profile.

"allows creation of a"

> +      The client is informed by an event if the color space of one of the
> +      outputs changes.
> +    </description>
> +
> +    <request name="set_colorspace">
> +      <description summary="set the color space of a wl_surface">
> +        With this request, the color space of a wl_surface can be set.
> +        Initially, the sRGB colorspace as returned by the srgb_colorspace
> +        request is attached to a surface.

The second sentence here is confusing to me.

> +      </description>
> +      <arg name="surface" type="object" interface="wl_surface" />
> +      <arg name="colorspace" type="object" interface="wl_cms_colorspace" />
> +    </request>
> +
> +    <request name="colorspace_from_fd">
> +      <description summary="creates a color space from an ICC profile">
> +        This request allows to create a wl_cms_colorspace object from an ICC

"allows creation of a"

> +        profile. The fd argument is the file descriptor to the ICC profile.

I don't know a whole lot about ICC profiles, but I do know that the
great thing about standards is that there's usually more than one...

>From http://www.color.org/registry/index.xalter it looks like there are
at least two versions of ICC (v2 and v4).  Would it be beneficial to
state explicitly what version(s) of the standard this supports?

> +      </description>
> +      <arg name="fd" type="fd" />
> +      <arg name="id" type="new_id" interface="wl_cms_colorspace" />
> +    </request>
> +
> +    <request name="output_colorspace">
> +      <description summary="returns the color space for the requested output">
> +        This request returns a wl_cms_colorspace object for the requested
> +        output. A client can use this when it does not want its surfaces to be
> +        color-corrected. In this case it can attach the color space of its main
> +        output to its surfaces.
> +      </description>
> +      <arg name="output" type="object" interface="wl_output" />
> +      <arg name="id" type="new_id" interface="wl_cms_colorspace" />
> +    </request>
> +
> +    <request name="srgb_colorspace">
> +      <description summary="tell the client what blending space is used">
> +        This request returns a wl_cms_colorspace object for the sRGB color
> +        space. The sRGB color space is initially attached to all surfaces.
> +      </description>
> +      <arg name="id" type="new_id" interface="wl_cms_colorspace" />
> +    </request>
> +
> +    <request name="blending_colorspace">
> +      <description summary="tell the client what blending space is used">
> +        This request returns a wl_cms_colorspace object for the blending color
> +        space of the compositor. All surfaces are converted by the compositor
> +        to the blending color space before the blending operations. A client
> +        should render in this color space if it does any color conversion on
> +        its own.
> +      </description>
> +      <arg name="id" type="new_id" interface="wl_cms_colorspace" />
> +    </request>

For someone with only foggy ideas of how colorspace support is
implemented, a picture of how these three colorspaces relate could be
invaluable.  Not sure how to integrate pictures into API docs, but maybe
there's a way.  If not, perhaps a bit more background explanation could
help here.

> +    <event name="output_colorspace_changed">
> +      <description summary="tell the client what color space an output has">
> +        This event will be sent when the color space of an output is changed.
> +      </description>
> +      <arg name="output" type="object" interface="wl_output" />
> +    </event>
> +
> +    <enum name="error">
> +      <entry name="invalid_profile" value="0"
> +             summary="the passed icc data is invalid" />
> +    </enum>
> +  </interface>
> +
> +  <interface name="wl_cms_colorspace" version="1">
> +    <description summary="represents a color space">
> +      This interface represents a color space that can be attached to surfaces.
> +      It is used by the wl_cms interface.
> +    </description>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="destroys the wl_cms_colorspace object">
> +        Informs the server that the client will not be using this protocol
> +        object anymore.
> +      </description>
> +    </request>
> +
> +    <request name="get_profile_fd">
> +      <description summary="get a file descriptor to the profile data">
> +        This request will cause a profile_fd event that returns a file
> +        descriptor to the ICC profile data of this colorspace.
> +      </description>
> +    </request>
> +
> +    <event name="profile_data">
> +      <description summary="file descriptor to the profile data">
> +        This event occurs after a get_profile_fd request and returns the file
> +        descriptor to the ICC profile data of this colorspace.
> +      </description>
> +      <arg name="fd" type="fd" />
> +    </event>
> +  </interface>
> +</protocol>

Reviewed-by: Bryce Harrington <b.harrington at samsung.com>

> -- 
> 2.1.2
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel