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>
e127c29d10