[PATCH wayland-protocols v3] Add alpha-compositing protocol

Discussion:

Scott Anderson

2018-11-15 01:00:28 UTC

This protocol specifies a set of interfaces used to control the alpha
compositing and blending of surface contents, based on the Chromium
Wayland protocol of the same name [1].

Signed-off-by: Scott Anderson <***@collabora.com>

[1] https://chromium.googlesource.com/chromium/src/+/master/third_party/wayland-protocols/unstable/alpha-compositing/alpha-compositing-unstable-v1.xml
---

Changes in v3:
- Rename "blending" event to "blending_equation"
- Add enum specifier to "blending_equation" event and "set_blending"
request.
- Fix typos

Changes in v2:
- Add additional "fromsource" blending equation used by [3]
- Allow the server to advertise which blending equations it supports
- Added a protocol error for using an unsupported equation
- Added a protocol error for using an invalid alpha value
- Added clarification about wl_surface.set_opaque_region
- Added clarification about per-pixel alpha values

Makefile.am | 1 +
unstable/alpha-compositing/README | 5 +
.../alpha-compositing-unstable-v1.xml | 175 ++++++++++++++++++
3 files changed, 181 insertions(+)
create mode 100644 unstable/alpha-compositing/README
create mode 100644 unstable/alpha-compositing/alpha-compositing-unstable-v1.xml

diff --git a/Makefile.am b/Makefile.am
index 6394e26..ac6c9f8 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -21,6 +21,7 @@ unstable_protocols = \
unstable/xdg-output/xdg-output-unstable-v1.xml \
unstable/input-timestamps/input-timestamps-unstable-v1.xml \
unstable/xdg-decoration/xdg-decoration-unstable-v1.xml \
+ unstable/alpha-compositing/alpha-compositing-unstable-v1.xml \
$(NULL)

stable_protocols = \
diff --git a/unstable/alpha-compositing/README b/unstable/alpha-compositing/README
new file mode 100644
index 0000000..5826967
--- /dev/null
+++ b/unstable/alpha-compositing/README
@@ -0,0 +1,5 @@
+Alpha compositing protocol
+
+Maintainers:
+David Reveman <***@chromium.org>
+Alexandros Frantzis <***@collabora.com>
diff --git a/unstable/alpha-compositing/alpha-compositing-unstable-v1.xml b/unstable/alpha-compositing/alpha-compositing-unstable-v1.xml
new file mode 100644
index 0000000..d3c41d5
--- /dev/null
+++ b/unstable/alpha-compositing/alpha-compositing-unstable-v1.xml
@@ -0,0 +1,175 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="alpha_compositing_unstable_v1">
+
+ <copyright>
+ Copyright 2016 The Chromium Authors.
+ Copyright 2017-2018 Collabora Ltd
+ Copyright 2018 NXP
+
+ 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="Protocol for more advanced compositing and blending">
+ This protocol specifies a set of interfaces used to control the alpha
+ compositing and blending of surface contents.
+
+ Warning! The protocol described in this file is experimental and backward
+ incompatible changes may be made. Backward compatible changes may be added
+ together with the corresponding interface version bump. Backward
+ incompatible changes are done by bumping the version number in the protocol
+ and interface names and resetting the interface version. Once the protocol
+ is to be declared stable, the 'z' prefix and the version number in the
+ protocol and interface names are removed and the interface version number is
+ reset.
+ </description>
+
+ <interface name="zwp_alpha_compositing_v1" version="1">
+ <description summary="alpha compositing">
+ The global interface exposing compositing and blending capabilities is
+ used to instantiate an interface extension for a wl_surface object.
+ This extended interface will then allow the client to specify the
+ blending equation and alpha value used for compositing the wl_surface.
+ </description>
+
+ <enum name="error">
+ <entry name="blending_exists" value="0"
+ summary="the surface already has a blending object associated"/>
+ </enum>
+
+ <request name="destroy" type="destructor">
+ <description summary="unbind from the blending interface">
+ Informs the server that the client will not be using this
+ protocol object anymore. This does not affect any other objects,
+ blending objects included.
+ </description>
+ </request>
+
+ <request name="get_blending">
+ <description summary="extend surface interface for blending">
+ Instantiate an interface extension for the given wl_surface to
+ provide surface blending. If the given wl_surface already has
+ a blending object associated, the BLENDING_EXISTS protocol error
+ is raised.
+ </description>
+
+ <arg name="id" type="new_id" interface="zwp_blending_v1"
+ summary="the new blending interface id"/>
+ <arg name="surface" type="object" interface="wl_surface"
+ summary="the surface"/>
+ </request>
+
+ <event name="blending_equation">
+ <description summary="supported blending equations">
+ This event advertises the blending equations that the server
+ supports. All the supported blending equations are advertised once
+ when the client binds to this interface. A roundtrip after binding
+ guarantees that the client has received all supported blending
+ equations.
+
+ For the definition of the blending equations, see the
+ zwp_blending_v1.blending_equation enum.
+
+ The server must always advertise the 'none' blending equation.
+ </description>
+ <arg name="blending_equation" type="uint"
+ enum="zwp_blending_v1.blending_equation"
+ summary="the blending equation"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_blending_v1" version="1">
+ <description summary="blending interface to a wl_surface">
+ An additional interface to a wl_surface object, which allows the
+ client to specify the blending equation used for compositing and
+ an alpha value applied to the whole surface.
+
+ When the blending object is created its blending equation is
+ 'none' and its alpha is 1.0, i.e., it's inactive by default. Clients
+ can activate it by setting the blending equation and alpha value.
+
+ Use of this interface has no effect on the surface's opaque region
+ as set by wl_surface.set_opaque_region. Clients must make sure to set
+ their opaque region correctly to prevent repaint artifacts.
+
+ If the wl_surface associated with the blending object is destroyed,
+ the blending object becomes inert.
+
+ If the blending object is destroyed, the blending state is removed
+ from the wl_surface. The change will be applied on the next
+ wl_surface.commit.
+ </description>
+
+ <enum name="blending_equation">
+ <description summary="different blending equations for compositing">
+ Blending equations that can be used when compositing a surface.
+ </description>
+ <entry name="none" value="0" summary="blending object is inactive"/>
+ <entry name="opaque" value="1" summary="(one, zero)"/>
+ <entry name="premultiplied" value="2" summary="(one, one_minus_src_alpha)"/>
+ <entry name="straight" value="3" summary="(src_alpha, one_minus_src_alpha)"/>
+ <entry name="fromsource" value="4" summary="(src_alpha, src_alpha)"/>
+ </enum>
+
+ <enum name="error">
+ <entry name="invalid_equation" value="0"
+ summary="the blending equation is not supported"/>
+ <entry name="invalid_alpha" value="1"
+ summary="the requested alpha value is outside the interval [0, 1]"/>
+ </enum>
+
+ <request name="destroy" type="destructor">
+ <description summary="remove blending from the surface">
+ The associated wl_surface's blending state is removed.
+ The change is applied on the next wl_surface.commit.
+ </description>
+ </request>
+
+ <request name="set_blending">
+ <description summary="set the blending equation">
+ Set the blending equation for compositing the wl_surface.
+
+ If the requested format was not advertised by the
+ zwp_alpha_compositing_v1.blending event, the INVALID_EQUATION protocol
+ error is raised.
+
+ The blending equation state is double-buffered state,
+ and will be applied on the next wl_surface.commit.
+ </description>
+ <arg name="equation" type="uint" enum="blending_equation"
+ summary="the new blending equation"/>
+ </request>
+
+ <request name="set_alpha">
+ <description summary="set the alpha value">
+ Set the alpha value applied to the whole surface for compositing. This
+ alpha value is applied as an additional step after the processing of
+ per-pixel alpha values for the wl_surface.
+
+ If the requested alpha is outside the interval [0, 1], the
+ INVALID_ALPHA protocol error is raised.
+
+ The alpha value state is double-buffered state,
+ and will be applied on the next wl_surface.commit.
+ </description>
+ <arg name="value" type="fixed" summary="the new alpha value"/>
+ </request>
+ </interface>
+
+</protocol>

--
2.19.1

Derek Foreman

2018-11-15 17:05:59 UTC

Permalink

This looks nice to me, and I have need of something like this.

A couple of comments below.

Post by Scott Anderson
This protocol specifies a set of interfaces used to control the alpha
compositing and blending of surface contents, based on the Chromium
Wayland protocol of the same name [1].
[1] https://chromium.googlesource.com/chromium/src/+/master/third_party/wayland-protocols/unstable/alpha-compositing/alpha-compositing-unstable-v1.xml
---
- Rename "blending" event to "blending_equation"
- Add enum specifier to "blending_equation" event and "set_blending"
request.
- Fix typos
- Add additional "fromsource" blending equation used by [3]
- Allow the server to advertise which blending equations it supports
- Added a protocol error for using an unsupported equation
- Added a protocol error for using an invalid alpha value
- Added clarification about wl_surface.set_opaque_region
- Added clarification about per-pixel alpha values
Makefile.am | 1 +
unstable/alpha-compositing/README | 5 +
.../alpha-compositing-unstable-v1.xml | 175 ++++++++++++++++++
3 files changed, 181 insertions(+)
create mode 100644 unstable/alpha-compositing/README
create mode 100644 unstable/alpha-compositing/alpha-compositing-unstable-v1.xml
diff --git a/Makefile.am b/Makefile.am
index 6394e26..ac6c9f8 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -21,6 +21,7 @@ unstable_protocols = \
unstable/xdg-output/xdg-output-unstable-v1.xml \
unstable/input-timestamps/input-timestamps-unstable-v1.xml \
unstable/xdg-decoration/xdg-decoration-unstable-v1.xml \
+ unstable/alpha-compositing/alpha-compositing-unstable-v1.xml \
$(NULL)
stable_protocols = \
diff --git a/unstable/alpha-compositing/README b/unstable/alpha-compositing/README
new file mode 100644
index 0000000..5826967
--- /dev/null
+++ b/unstable/alpha-compositing/README
@@ -0,0 +1,5 @@
+Alpha compositing protocol
+
diff --git a/unstable/alpha-compositing/alpha-compositing-unstable-v1.xml b/unstable/alpha-compositing/alpha-compositing-unstable-v1.xml
new file mode 100644
index 0000000..d3c41d5
--- /dev/null
+++ b/unstable/alpha-compositing/alpha-compositing-unstable-v1.xml
@@ -0,0 +1,175 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="alpha_compositing_unstable_v1">
+
+ <copyright>
+ Copyright 2016 The Chromium Authors.
+ Copyright 2017-2018 Collabora Ltd
+ Copyright 2018 NXP
+
+ 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
+
+ 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="Protocol for more advanced compositing and blending">
+ This protocol specifies a set of interfaces used to control the alpha
+ compositing and blending of surface contents.
+
+ Warning! The protocol described in this file is experimental and backward
+ incompatible changes may be made. Backward compatible changes may be added
+ together with the corresponding interface version bump. Backward
+ incompatible changes are done by bumping the version number in the protocol
+ and interface names and resetting the interface version. Once the protocol
+ is to be declared stable, the 'z' prefix and the version number in the
+ protocol and interface names are removed and the interface version number is
+ reset.
+ </description>
+
+ <interface name="zwp_alpha_compositing_v1" version="1">
+ <description summary="alpha compositing">
+ The global interface exposing compositing and blending capabilities is
+ used to instantiate an interface extension for a wl_surface object.
+ This extended interface will then allow the client to specify the
+ blending equation and alpha value used for compositing the wl_surface.
+ </description>
+
+ <enum name="error">
+ <entry name="blending_exists" value="0"
+ summary="the surface already has a blending object associated"/>
+ </enum>
+
+ <request name="destroy" type="destructor">
+ <description summary="unbind from the blending interface">
+ Informs the server that the client will not be using this
+ protocol object anymore. This does not affect any other objects,
+ blending objects included.
+ </description>
+ </request>
+
+ <request name="get_blending">
+ <description summary="extend surface interface for blending">
+ Instantiate an interface extension for the given wl_surface to
+ provide surface blending. If the given wl_surface already has
+ a blending object associated, the BLENDING_EXISTS protocol error
+ is raised.
+ </description>
+
+ <arg name="id" type="new_id" interface="zwp_blending_v1"
+ summary="the new blending interface id"/>
+ <arg name="surface" type="object" interface="wl_surface"
+ summary="the surface"/>
+ </request>
+
+ <event name="blending_equation">
+ <description summary="supported blending equations">
+ This event advertises the blending equations that the server
+ supports. All the supported blending equations are advertised once
+ when the client binds to this interface. A roundtrip after binding
+ guarantees that the client has received all supported blending
+ equations.
+
+ For the definition of the blending equations, see the
+ zwp_blending_v1.blending_equation enum.
+
+ The server must always advertise the 'none' blending equation.

Would it make sense to require the server to advertise 'none' last, so
clients can treat it as an end-of-list?

Post by Scott Anderson
+ </description>
+ <arg name="blending_equation" type="uint"
+ enum="zwp_blending_v1.blending_equation"
+ summary="the blending equation"/>
+ </event>
+ </interface>
+
+ <interface name="zwp_blending_v1" version="1">
+ <description summary="blending interface to a wl_surface">
+ An additional interface to a wl_surface object, which allows the
+ client to specify the blending equation used for compositing and
+ an alpha value applied to the whole surface.
+
+ When the blending object is created its blending equation is
+ 'none' and its alpha is 1.0, i.e., it's inactive by default. Clients
+ can activate it by setting the blending equation and alpha value.
+
+ Use of this interface has no effect on the surface's opaque region
+ as set by wl_surface.set_opaque_region. Clients must make sure to set
+ their opaque region correctly to prevent repaint artifacts.
+
+ If the wl_surface associated with the blending object is destroyed,
+ the blending object becomes inert.
+
+ If the blending object is destroyed, the blending state is removed
+ from the wl_surface. The change will be applied on the next
+ wl_surface.commit.
+ </description>
+
+ <enum name="blending_equation">
+ <description summary="different blending equations for compositing">
+ Blending equations that can be used when compositing a surface.
+ </description>
+ <entry name="none" value="0" summary="blending object is inactive"/>
+ <entry name="opaque" value="1" summary="(one, zero)"/>
+ <entry name="premultiplied" value="2" summary="(one, one_minus_src_alpha)"/>
+ <entry name="straight" value="3" summary="(src_alpha, one_minus_src_alpha)"/>
+ <entry name="fromsource" value="4" summary="(src_alpha, src_alpha)"/>
+ </enum>
+
+ <enum name="error">
+ <entry name="invalid_equation" value="0"
+ summary="the blending equation is not supported"/>
+ <entry name="invalid_alpha" value="1"
+ summary="the requested alpha value is outside the interval [0, 1]"/>
+ </enum>
+
+ <request name="destroy" type="destructor">
+ <description summary="remove blending from the surface">
+ The associated wl_surface's blending state is removed.
+ The change is applied on the next wl_surface.commit.
+ </description>
+ </request>
+
+ <request name="set_blending">
+ <description summary="set the blending equation">
+ Set the blending equation for compositing the wl_surface.
+
+ If the requested format was not advertised by the
+ zwp_alpha_compositing_v1.blending event, the INVALID_EQUATION protocol
+ error is raised.
+
+ The blending equation state is double-buffered state,
+ and will be applied on the next wl_surface.commit.
+ </description>
+ <arg name="equation" type="uint" enum="blending_equation"
+ summary="the new blending equation"/>
+ </request>
+
+ <request name="set_alpha">
+ <description summary="set the alpha value">
+ Set the alpha value applied to the whole surface for compositing. This
+ alpha value is applied as an additional step after the processing of
+ per-pixel alpha values for the wl_surface.
+
+ If the requested alpha is outside the interval [0, 1], the
+ INVALID_ALPHA protocol error is raised.
+
+ The alpha value state is double-buffered state,
+ and will be applied on the next wl_surface.commit.
+ </description>
+ <arg name="value" type="fixed" summary="the new alpha value"/>

I worry about using wl_fixed here, as it only has 8 bits of decimal
precision, and >8bpc seems to be increasingly common these days...

Thanks,
Derek

Post by Scott Anderson
+ </request>
+ </interface>
+
+</protocol>

Scott Anderson

2018-11-16 09:59:20 UTC

Permalink

Post by Derek Foreman
This looks nice to me, and I have need of something like this.
A couple of comments below.

Would it make sense to require the server to advertise 'none' last, so
clients can treat it as an end-of-list?

With the guarantee that you'll receive them all after a roundtrip, an
end-of-list marker isn't necessary. This is what wp_linux_dmabuf does.

Post by Derek Foreman

I worry about using wl_fixed here, as it only has 8 bits of decimal
precision, and >8bpc seems to be increasingly common these days...
Thanks,
Derek

I'm not aware of any format (of those listed in drm_fourcc.h) that has
over 8 bits for alpha. For the 10bpc formats that are out there (e.g.
ARGB2101010), the alpha gets smaller.

There is also the question of what the range should be. Do we change
this to a uint and map 0xffffffff to 1.0, and 0x00000000 to 0.0? That
seems a little awkward to me, but not terrible.

It's not something I'm opposed to changing, but I don't think it's
necessary.

Post by Derek Foreman

Post by Scott Anderson
+ </request>
+ </interface>
+
+</protocol>

_______________________________________________
wayland-devel mailing list
https://lists.freedesktop.org/mailman/listinfo/wayland-devel

Simon Ser

2018-11-16 08:39:14 UTC

Permalink

Post by Derek Foreman

Post by Scott Anderson
+ <event name="blending_equation">
+ <description summary="supported blending equations">
+ This event advertises the blending equations that the server
+ supports. All the supported blending equations are advertised once
+ when the client binds to this interface. A roundtrip after binding
+ guarantees that the client has received all supported blending
+ equations.
+
+ For the definition of the blending equations, see the
+ zwp_blending_v1.blending_equation enum.
+
+ The server must always advertise the 'none' blending equation.

Would it make sense to require the server to advertise 'none' last, so
clients can treat it as an end-of-list?

I'm not a fan of this idea. If it is really needed, a "done" event would be
better. However, the list is advertised once on bind and doesn't change, so I
don't think this is necessary. Just making clients do a roundtrip should be
enough (as it's done in other protocols like linux-dmabuf).

Simon Ser

2018-11-16 08:41:15 UTC

Permalink

This version LGTM.

Reviewed-by: Simon Ser <***@emersion.fr>

Thanks!