protocol: change wl_surface.enter/leave wording

The existing wording has been carried from the introduction of the enter
and leave events in

commit a5df3de101
Date:   Tue Apr 17 17:22:45 2012 -0400

    Add wl_surface.enter and wl_surface.leave events

However, the modern understanding is that a surface cannot enter an
output unless it would actually be shown there, at least if no other
surfaces existed in the compositor. For a surface to be shown, it must
mapped, and it cannot be mapped without contents and a role. A
wl_surface is created without contents and without a role, so simply
creating a wl_surface cannot result in enter events.

The enter and leave events have traditionally been used to infer the
output scale and tranform that would be best for the client to use. This
is indirect, somewhat vague, and does not work for a surface's initial
drawing, which is why the wl_surface events preferred_buffer_scale and
preferred_buffer_transform were introduced. This removes any remaining
doubt that enter could be triggered simply by creating a wl_surface.

Therefore, let's fix the wording here.

Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
This commit is contained in:
Pekka Paalanen 2023-09-18 11:53:28 +03:00
parent edb943dc64
commit e127c29d10

View file

@ -1662,7 +1662,7 @@
<event name="enter">
<description summary="surface enters an output">
This is emitted whenever a surface's creation, movement, or resizing
This is emitted whenever a surface's mapping, movement, or resizing
results in some part of it being within the scanout region of an
output.
@ -1673,7 +1673,7 @@
<event name="leave">
<description summary="surface leaves an output">
This is emitted whenever a surface's creation, movement, or resizing
This is emitted whenever a surface's unmapping, movement, or resizing
results in it no longer having any part of it within the scanout region
of an output.