protocol: make it clear wl_surface.enter/leave are not for frame throttling

Some clients rely on wl_surface.enter/leave to start/stop their rendering
loop.

There are cases where this doesn't work:

- Some compositors don't send wl_surface.leave when a toplevel is hidden.
  For instance Sway doesn't send this event when a toplevel is on an inactive
  workspace (but doesn't send wl_surface.frame events).
- Some compositors might still want applications to continue to render even if
  away from outputs. For instance a compositor that allows to screen record
  individual toplevels might not send a wl_surface.enter event for hidden
  toplevels.

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

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 3475a79..f896818 100644 (file)
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1609,6 +1609,12 @@
        This is emitted whenever a surface's creation, movement, or resizing
        results in it no longer having any part of it within the scanout region
        of an output.
+
+       Clients should not use the number of outputs the surface is on for frame
+       throttling purposes. The surface might be hidden even if no leave event
+       has been sent, and the compositor might expect new surface content
+       updates even if no enter event has been sent. The frame event should be
+       used instead.
       </description>
       <arg name="output" type="object" interface="wl_output" summary="output left by the surface"/>
     </event>