[PATCH wayland-protocols v3] Add alpha-compositing protocol
Pekka Paalanen
ppaalanen at gmail.com
Tue Dec 18 15:19:37 UTC 2018
On Thu, 15 Nov 2018 14:00:28 +1300
Scott Anderson <scott.anderson at collabora.com> wrote:
> 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 <scott.anderson at 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 <reveman at chromium.org>
> +Alexandros Frantzis <alexandros.frantzis at 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.
Hi,
I'm a little bit wary of adding extensions like this, it seems to be
pushing Wayland towards a rendering API.
Could you explain in the commit message what this protocol is used for,
please?
I can imagine cases, but I would like it written down what actual use
case is driving this proposal.
> +
> + 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.
Alpha value for the whole surface is ok.
The blending equation is what I do not like, because, if I understood
right what is being blended, it implies the client could control the
result of the blending with certain expectations. The problem with that
is that a client cannot (usually) know what it is being blended with.
Describing the properties of your wl_surface is good, but expecting a
compositor to composite it in a specific way for a particular result is
less so.
> +
> + 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.
What is the confusion you try to clarify with this paragraph?
If a client sets the surface alpha to < 1.0, how should it then set the
opaque region? Do you mean that the opaque region the client is
setting must already take into account the surface alpha? IOW, if
surface alpha < 1.0, then opaque region must always be empty?
> +
> + 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)"/>
The above are not that much blending equations. Instead, they describe
the contents of the buffer: "opaque" is just yet another way to discard
alpha (this time guaranteed, unlike the opaque region, but you could as
well just use a different pixel format), "premultiplied" is what
everything in Wayland by default is, and "straight" is the new thing.
Furthermore, "none" is equivalent to "premultiplied" with surface alpha
set to 1.0, so it seems unnecessary. "none" is also redundant with
not-creating or destroying the blending object.
> + <entry name="fromsource" value="4" summary="(src_alpha, src_alpha)"/>
What is this good for? The four above can be interpreted as describing
the surface alone, but this I'm not sure.
I think the summaries refer to OpenGL blending settings, but that is
not enough to explain them.
If the fifth can also be written as describing the wl_surface alone
without making any statement about what it is being blended with, then
I think we can resolve all my objections by just adjusting the
terminology.
But, if the aim really is to control blending, not simply describe the
wl_surface of the client, then you should also think about the blending
space. I assume most compositors blend in sRGB space, but that is quite
incorrect, even if it leads to ok'ish results for an uneducated viewer.
Blending should be done in a linear space, even if one does not bring
up all the actual color space stuff from color management.
> + </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.
What formula does "applying the alpha value" follow? Please be more
specific, I'm not sure if it applies before or after the blending
equation (surface description).
> +
> + 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"/>
Since there is no use for values outside of the [0, 1] interval, using
wl_fixed type with its limited fractional precision is not so useful.
Maybe the mentioned [0, 0xffffffff] or [0, 0xffff] ranges mapped to
[0.0, 1.0] would be more approriate? IIRC Pixman uses 16-bit components
for constant colors, for instance. DRM probably too.
> + </request>
> + </interface>
> +
> +</protocol>
Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20181218/8c3ca9b7/attachment-0001.sig>
More information about the wayland-devel
mailing list