Skip to content

protocol: change wl_surface.enter/leave wording

Pekka Paalanen requested to merge pq/wayland:mr/surface_enter into main

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

commit a5df3de1 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.

Merge request reports