stable/xdg-shell: allow compositors to support transparent fullscreen windows

Not all compositors enforce fullscreen windows to be opaque, and for some applications
(terminal emulators) it can make sense for the window to be translucent even while the
window is fullscreen.
At the same time, it can be beneficial for applications to rely on the compositor
to  enforce opaqueness and scale the surface, and some compositors want to use
fullscreen transparency as a security feature, so both behaviors have to be supported
by the protocol.

To cover these issues, this commit
1. changes set_fullscreen to no longer require compositors to enforce opaqueness.
   Compositors are still allowed and recommended to do it, but the actually applied
   behavior is compositor policy, which matches how it works in practice today
2. adds a set_fullscreen_2 request, where the client can ask for a specific behavior,
   either enforcing opaqueness and centering, or allowing transparency. Clients can
   find out if their desired behavior is supported with the matching wm_capabilities
   enum values.

Signed-off-by: Xaver Hugl <xaver.hugl@kde.org>

stable/xdg-shell/xdg-shell.xml

@@ -29,7 +29,7 @@
     DEALINGS IN THE SOFTWARE.
   </copyright>
 
-  <interface name="xdg_wm_base" version="6">
+  <interface name="xdg_wm_base" version="7">
     <description summary="create desktop-style surfaces">
       The xdg_wm_base interface is exposed as a global object enabling clients
       to turn their wl_surfaces into windows in a desktop environment. It
@@ -617,7 +617,7 @@
 
   </interface>
 
-  <interface name="xdg_toplevel" version="6">
+  <interface name="xdg_toplevel" version="7">
     <description summary="toplevel surface">
       This interface defines an xdg_surface role which allows a surface to,
       among other things, set window-like properties such as maximize,
@@ -1058,16 +1058,16 @@
 	it's up to the compositor to choose which display will be used to map
 	this surface.
 
-	If the surface doesn't cover the whole output, the compositor will
-	position the surface in the center of the output and compensate with
-	with border fill covering the rest of the output. The content of the
-	border fill is undefined, but should be assumed to be in some way that
-	attempts to blend into the surrounding area (e.g. solid black).
+        If the surface doesn't cover the whole output or isn't opaque,
+        the compositor may apply either of the behaviors described by the
+        fullscreen_behavior enum.
+        While compositors are recommended to apply the opaqueness_enforced
+        behavior for best backwards compatibility with protocol versions 6
+        and ealier, this is not implemented by all compositors, so clients
+        can't fully rely on it.
 
-	If the fullscreened surface is not opaque, the compositor must make
-	sure that other screen content not part of the same surface tree (made
-	up of subsurfaces, popups or similarly coupled surfaces) are not
-	visible below the fullscreened surface.
+        If a specific behavior is desired, it should be explicitly requested
+        with set_fullscreen_2.
       </description>
       <arg name="output" type="object" interface="wl_output" allow-null="true"/>
     </request>
@@ -1176,8 +1176,16 @@
     <enum name="wm_capabilities" since="5">
       <entry name="window_menu" value="1" summary="show_window_menu is available"/>
       <entry name="maximize" value="2" summary="set_maximized and unset_maximized are available"/>
-      <entry name="fullscreen" value="3" summary="set_fullscreen and unset_fullscreen are available"/>
+      <entry name="fullscreen" value="3">
+        <description summary="set_fullscreen and unset_fullscreen are available">
+          Starting with version 7, this also means set_fullscreen_2 is available.
+        </description>
+      </entry>
       <entry name="minimize" value="4" summary="set_minimized is available"/>
+      <entry name="opaque_fullscreen" value="5"
+             summary="fullscreen behavior opaqueness_enforced is available" since="7"/>
+      <entry name="transparent_fullscreen" value="6"
+             summary="fullscreen behavior transparency_allowed is available" since="7"/>
     </enum>
 
     <event name="wm_capabilities" since="5">
@@ -1205,9 +1213,55 @@
       </description>
       <arg name="capabilities" type="array" summary="array of 32-bit capabilities"/>
     </event>
+
+    <enum name="fullscreen_behavior" since="7">
+      <entry name="opaqueness_enforced" value="0">
+        <description summary="no surfaces below the window are shown">
+          If the surface doesn't cover the whole output, the compositor will
+          position the surface in the center of the output and compensate with
+          with border fill covering the rest of the output. The content of the
+          border fill is undefined, but should be assumed to be in some way that
+          attempts to blend into the surrounding area (e.g. solid black).
+
+          If the fullscreened surface is not opaque, the compositor must make
+          sure that other screen content not part of the same surface tree (made
+          up of subsurfaces, popups or similarly coupled surfaces) are not
+          visible below the fullscreened surface.
+        </description>
+      </entry>
+      <entry name="transparency_allowed" value="1">
+        <description summary="surfaces below the window may be shown">
+          If the surface doesn't cover the whole output, the behavior is
+          compositor-specific. The client should avoid this situation.
+
+          If the fullscreened surface is not opaque, the compositor should
+          show elements below the surface tree.
+        </description>
+      </entry>
+      <entry name="dont_care" value="2" summary="the compositor should choose"/>
+    </enum>
+
+    <request name="set_fullscreen_2" since="7">
+      <description summary="set the window as fullscreen on an output">
+        Make the surface fullscreen with the desired behavior.
+
+        After requesting that the surface should be fullscreened, the
+        compositor will respond by emitting a configure event. Whether the
+        client is actually put into a fullscreen state is subject to compositor
+        policies. The client must also acknowledge the configure when
+        committing the new content (see ack_configure).
+
+        The output passed by the request indicates the client's preference as
+        to which display it should be set fullscreen on. If this value is NULL,
+        it's up to the compositor to choose which display will be used to map
+        this surface.
+      </description>
+      <arg name="output" type="object" interface="wl_output" allow-null="true"/>
+      <arg name="desired_behavior" type="uint" enum="fullscreen_behavior"/>
+    </request>
   </interface>
 
-  <interface name="xdg_popup" version="6">
+  <interface name="xdg_popup" version="7">
     <description summary="short-lived, popup surfaces for menus">
       A popup surface is a short-lived, temporary surface. It can be used to
       implement for example menus, popovers, tooltips and other similar user