Hi, Here are a few more comments in addition to Pekka's ones.
On Monday, March 18, 2019 3:12 AM, Sebastian Wick <[email protected]> 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 <[email protected]> > --- > 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 <[email protected]> > 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 > [email protected] > https://lists.freedesktop.org/mailman/listinfo/wayland-devel _______________________________________________ wayland-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/wayland-devel
