[RFC wayland-protocols v3 1/1] unstable: add color management protocol
Simon Ser
contact at emersion.fr
Wed Mar 20 20:45:45 UTC 2019
Hi,
Here are a few more comments in addition to Pekka's ones.
On Monday, March 18, 2019 3:12 AM, Sebastian Wick <sebastian at sebastianwick.net> wrote:
> This protocol allows clients to attach a color space, rendering intent
> and HDR information to surfaces and to query outputs about their color
> spaces and HDR capabilities.
>
> Signed-off-by: Sebastian Wick <sebastian at sebastianwick.net>
> ---
> Makefile.am | 1 +
> unstable/color-management/README | 4 +
> .../color-management-unstable-v1.xml | 228 ++++++++++++++++++
> 3 files changed, 233 insertions(+)
> create mode 100644 unstable/color-management/README
> create mode 100644 unstable/color-management/color-management-unstable-v1.xml
>
> diff --git a/Makefile.am b/Makefile.am
> index 345ae6a..80abc1d 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -23,6 +23,7 @@ unstable_protocols = \
> unstable/xdg-decoration/xdg-decoration-unstable-v1.xml \
> unstable/linux-explicit-synchronization/linux-explicit-synchronization-unstable-v1.xml \
> unstable/primary-selection/primary-selection-unstable-v1.xml \
> + unstable/color-management/color-management-unstable-v1.xml \
> $(NULL)
>
> stable_protocols = \
> diff --git a/unstable/color-management/README b/unstable/color-management/README
> new file mode 100644
> index 0000000..140f1e9
> --- /dev/null
> +++ b/unstable/color-management/README
> @@ -0,0 +1,4 @@
> +Color management protocol
> +
> +Maintainers:
> +Sebastian Wick <sebastian at sebastianwick.net>
> diff --git a/unstable/color-management/color-management-unstable-v1.xml b/unstable/color-management/color-management-unstable-v1.xml
> new file mode 100644
> index 0000000..7b4d08e
> --- /dev/null
> +++ b/unstable/color-management/color-management-unstable-v1.xml
> @@ -0,0 +1,228 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<protocol name="color_management_unstable_v1">
> +
> + <copyright>
> + Copyright © 2019 Sebastian Wick
> + Copyright © 2019 Erwin Burema
> +
> + Permission is hereby granted, free of charge, to any person obtaining a
> + copy of this software and associated documentation files (the "Software"),
> + to deal in the Software without restriction, including without limitation
> + the rights to use, copy, modify, merge, publish, distribute, sublicense,
> + and/or sell copies of the Software, and to permit persons to whom the
> + Software is furnished to do so, subject to the following conditions:
> +
> + The above copyright notice and this permission notice (including the next
> + paragraph) shall be included in all copies or substantial portions of the
> + Software.
> +
> + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
> + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
> + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
> + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
> + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
> + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
> + DEALINGS IN THE SOFTWARE.
> + </copyright>
> +
> + <description summary="color management protocol">
> + This protocol specifies a way for a client to set the color space and
> + HDR metadata of a surface and to get information about the color spaces
> + and HDR capabilities of outputs.
> + </description>
> +
> + <interface name="zwp_color_manager_v1" version="1">
> + <description summary="color manager">
> + A global interface used for getting color management surface and color
> + management output objects as well as creating color spaces from ICC
> + profiles.
> + </description>
> +
> + <enum name="error">
> + <description summary="fatal color manager errors">
> + These fatal protocol errors may be emitted in response to illegal color
> + management requests.
> + </description>
> + <entry name="invalid_icc_profile" value="0" summary="invalid ICC profile"/>
> + </enum>
> +
> + <request name="create_color_space">
> + <description summary="create a color space object">
> + Create a color space object from an ICC profile.
> +
> + Only three channel display profiles are allowed. The file descriptor
> + must be mmap-able. If the conditions are not met a protocol error
> + "invalid_icc_profile" is raised by the compositor.
As Pekka said, it would be better to add more access restrictions to the mmap'ed
region. In addition to saying the compositor shouldn't write to it, I believe we
should also require the compositor to map it with MAP_PRIVATE. See the
wl_keyboard.keymap event docs:
> From version 7 onwards, the fd must be mapped with MAP_PRIVATE by
> the recipient, as MAP_SHARED may fail.
> + See the zwp_color_space interface for more details about the created
Interfaces names should either be in their stable form ("wp_color_space") or
their unstable one ("zwp_color_space_v1").
> + object.
> +
> + See the ICC specification for more details about ICC profiles.
> + </description>
> + <arg name="id" type="new_id" interface="zwp_color_space_v1"/>
> + <arg name="icc" type="fd"/>
> + </request>
> +
> + <request name="get_color_management_output">
> + <description summary="create a color management output from a wl_output">
> + This creates a new color zwp_color_management_output object for the
> + given wl_output.
> +
> + See the zwp_color_management_output interface for more details.
> + </description>
> + <arg name="id" type="new_id" interface="zwp_color_management_output_v1"/>
> + <arg name="output" type="object" interface="wl_output"/>
> + </request>
> +
> + <request name="get_color_management_surface">
> + <description summary="create a color management surface from a wl_surface">
> + This creates a new color zwp_color_management_surface object for the
> + given wl_surface.
What happens if two zwp_color_management_surface_v1 objects are created for the
same wl_surface?
Many protocols just disallow this and send a protocol error.
> + See the zwp_color_management_surface interface for more details.
> + </description>
> + <arg name="id" type="new_id" interface="zwp_color_management_surface_v1"/>
> + <arg name="surface" type="object" interface="wl_surface"/>
> + </request>
> +
> + <request name="destroy" type="destructor">
> + <description summary="destroy the color manager">
> + Destroy the zwp_color_manager object.
> + </description>
> + </request>
> + </interface>
> +
> + <interface name="zwp_color_management_output_v1" version="1">
> + <description summary="output color properties">
> + A zwp_color_management_output describes the color properties of an
> + output.
Pekka suggested to make the object inert when the proxy is destroyed. I'm not
sure this is required as long as the compositor state doesn't _need_ to
reference the resource. But it should at least become inert when the output is
destroyed.
> + </description>
> +
> + <event name="color_space_changed">
> + <description summary="color space changed">
> + The color_space_changed event is sent after creating an zwp_color_management_output
> + (see zwp_color_manager.get_color_management_output) and whenever the color
> + space of the output changed.
> + </description>
> + </event>
> +
> + <request name="get_color_space">
> + <description summary="get the color space of the output">
> + This creates a new zwp_color_space object for the current color space of
> + the output. There always is exactly one color space active so the client
> + should destroy the color space created by earlier invocations of this
> + request. This is usually called as a reaction to the color_space_changed
> + event.
> +
> + See the zwp_color_space interface for more details.
> + </description>
> + <arg name="id" type="new_id" interface="zwp_color_space_v1"/>
> + </request>
> +
> + <!-- TODO: HDR capabilities event -->
> +
> + <request name="destroy" type="destructor">
> + <description summary="destroy the color management output">
> + Destroy the color zwp_color_management_output object.
> + </description>
> + </request>
> + </interface>
> +
> + <interface name="zwp_color_management_surface_v1" version="1">
> + <description summary="set color management information of a surface">
> + A zwp_color_management_surface allows the client to set the color space and
> + HDR properties of a surface.
> + </description>
> +
> + <enum name="render_intent">
> + <description summary="render intent">
> + Rendering intent allow the client to hint at how to perform color space
> + transformations.
> +
> + See the ICC specification for more details about rendering intent.
> + </description>
> + <entry name="absolute" value="1" summary="ICC-absolute colorimetric"/>
> + <entry name="relative" value="2" summary="media-relative colorimetric"/>
> + <entry name="perceptual" value="3" summary="perceptual"/>
> + <entry name="saturation" value="4" summary="saturation"/>
> + </enum>
> +
> + <request name="set_color_space">
> + <description summary="set the color space">
> + Set the color space of the underlying surface. The color space is double
> + buffered, and will be applied at the time wl_surface.commit of the
> + corresponding wl_surface is called.
> +
> + The render intent gives the compositor a hint what to optimize for in
> + color space transformations.
> +
> + The corresponding buffer is expected to contain un-premultiplied pixels when
> + a color space is set with this request.
> +
> + If a surface has no color space set, sRGB and an arbitrary render intent
> + will be assumed.
> +
> + If the color space of the surface matches the color space of an output
> + it is shown on the performance and color accuracy might improve. To find
> + those color spaces the client can listen to the preferred_color_space or
> + the wl_surface.enter/leave events.
> + </description>
> + <arg name="color_space" type="object" interface="zwp_color_space_v1"/>
> + <arg name="render_intent" type="uint" enum="render_intent"/>
> + </request>
> +
> + <!-- TODO: HDR metadata request -->
> +
> + <event name="preferred_color_space">
> + <description summary="preferred color space">
> + The preferred_color_space event is sent after creating an
> + zwp_color_management_surface (see zwp_color_manager.get_color_management_surface)
> + and whenever the preferred color space changed.
> +
> + The event does not carry a zwp_color_space but a wl_output object. The
> + concret zwp_color_space can be created by calling
> + zwp_color_management_output.get_color_space on the output.
> +
> + This is only a hint and clients can set any valid color space with
> + set_color_space but there might be performance and color accuracy
> + improvements by providing the surface in the preferred color space.
> + </description>
> + <arg name="output" type="object" interface="wl_output"/>
> + </event>
> +
> + <request name="destroy" type="destructor">
> + <description summary="destroy the color management surface">
> + Destroy the zwp_color_management_surface object.
> + </description>
> + </request>
> + </interface>
> +
> + <interface name="zwp_color_space_v1" version="1">
> + <description summary="color space">
> + Describes a color space which can be attached to a surface
> + (zwp_color_management_surface.set_color_space) and provides information
> + like the ICC profile to alow clients to do color space transformations.
> +
> + The client can create a zwp_color_space object from an ICC profile by
> + calling zwp_color_manager.create_color_space or from an output by
> + calling zwp_color_management_output.get_color_space.
> + </description>
> +
> + <event name="information">
> + <description summary="color space information">
> + Information describing the color space is send once after binding.
> +
> + The icc argument contains a mmap-able fd to the corresponding ICC
> + profile.
> + </description>
> + <arg name="icc" type="fd"/>
> + </event>
> +
> + <request name="destroy" type="destructor">
> + <description summary="destroy the color space">
> + Destroy the zwp_color_space object.
> + </description>
> + </request>
> + </interface>
> +
> +</protocol>
> --
> 2.20.1
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel
More information about the wayland-devel
mailing list