[PATCH wayland-protocols v3 18/17] xdg-shell: Soften fullscreen geometry requirements

[Jonas Ådahl]

Having a strict requirement on clients obeying the configured window
geometry for fullscreen toplevel surfaces might have the side effect of
making it harder or impossible to implement various hardware
optimizations on certain system configurations. By softening
requirements on the geometry while loosely defining the border fill, we
remove that restriction.

Clients that still want total control of the surrounding area can
still for example prepare the attached buffers to match the configured
surface size, or use subsurfaces in combination with wp_viewporter to
make up a surface matching the fullscreen window geometry dimensions.

Signed-off-by: Jonas Ådahl <jadahl at gmail.com>
---
 stable/xdg-shell/xdg-shell.xml | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/stable/xdg-shell/xdg-shell.xml b/stable/xdg-shell/xdg-shell.xml
index 34e3a20..dc70c7a 100644
--- a/stable/xdg-shell/xdg-shell.xml
+++ b/stable/xdg-shell/xdg-shell.xml
@@ -728,8 +728,11 @@
       </entry>
       <entry name="fullscreen" value="2" summary="the surface is fullscreen">
 	<description summary="the surface is fullscreen">
-	  The surface is fullscreen. The window geometry specified in the configure
-	  event must be obeyed by the client.
+	  The surface is fullscreen. The window geometry specified in the
+	  configure event is a maximum; the client cannot resize beyond it. For
+	  a surface to cover the whole fullscreened area, the geometry
+	  dimensions must be obeyed by the client. For more details, see
+	  xdg_toplevel.set_fullscreen.
 	</description>
       </entry>
       <entry name="resizing" value="3" summary="the surface is being resized">
@@ -888,7 +891,7 @@
 
 	After requesting that the surface should be fullscreened, the
 	compositor will respond by emitting a configure event with the
-	"fullscreen" state and the required window geometry. The client must
+	"fullscreen" state and the fullscreen window geometry. The client must
 	also acknowledge the configure when committing the new content (see
 	ack_configure).
 
@@ -899,7 +902,14 @@
 
 	If the surface doesn't cover the whole output, the compositor will
 	position the surface in the center of the output and compensate with
-	black borders filling the rest of the output.
+	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>
       <arg name="output" type="object" interface="wl_output" allow-null="true"/>
     </request>
-- 
2.14.2