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

Submitted by Scott Anderson on Nov. 15, 2018, 1 a.m.

Details

Message ID 20181115010028.18410-1-scott.anderson@collabora.com
State New
Headers show
Series "Add alpha-compositing protocol" ( rev: 3 ) in Wayland

Not browsing as part of any series.

Commit Message

Scott Anderson Nov. 15, 2018, 1 a.m.
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@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

Patch hide | download patch | download mbox

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@chromium.org>
+Alexandros Frantzis <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>

Comments

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

A couple of comments below.

On 11/14/18 7:00 PM, Scott Anderson 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@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@chromium.org>
> +Alexandros Frantzis <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.

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

> +      </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

> +    </request>
> +  </interface>
> +
> +</protocol>
>
On Thursday, November 15, 2018 2:00 AM, Scott Anderson <scott.anderson@collabora.com> wrote:
> > +    <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).
> 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@collabora.com>

This version LGTM.

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

Thanks!
On 16/11/18 6:05 am, Derek Foreman wrote:
> This looks nice to me, and I have need of something like this.
> 
> A couple of comments below.
> 
> On 11/14/18 7:00 PM, Scott Anderson 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@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@chromium.org>
>> +Alexandros Frantzis <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.
> 
> 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.

>> +      </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
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.

> 
>> +    </request>
>> +  </interface>
>> +
>> +</protocol>
>>
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel
>
On Thu, 15 Nov 2018 14:00:28 +1300
Scott Anderson <scott.anderson@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@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@chromium.org>
> +Alexandros Frantzis <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.

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