From: Pekka Paalanen <pekka.paala...@collabora.co.uk> Define what a role is, and what restrictions there are.
A change to existing behaviour is that a role cannot be changed at all once set. However, this is unlikely to cause problems, as there is no reason to re-use wl_surfaces in clients. Signed-off-by: Pekka Paalanen <pekka.paala...@collabora.co.uk> --- protocol/wayland.xml | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/protocol/wayland.xml b/protocol/wayland.xml index 2d57f69..39af61f 100644 --- a/protocol/wayland.xml +++ b/protocol/wayland.xml @@ -973,8 +973,24 @@ local coordinates of the pixel content, in case a buffer_transform or a buffer_scale is used. - Surfaces are also used for some special purposes, e.g. as - cursor images for pointers, drag icons, etc. + A surface without a "role" is fairly useless, a compositor does not + know where, when or how to present it. The role is the purpose of a + wl_surface. Examples of roles are a cursor for a pointer, a drag icon, + a sub-surface, and a window as defined by a shell protocol. + + A surface can have only one role at a time. Initially a wl_surface + does not have a role. Once a role is set, it can never be set to a + different role again. + + A role is set by a request in another interface than wl_surface + itself. The protocol specification of the other interface + defines, that the request gives a specific role to a wl_surface. + Often, this request also creates a new protocol object, that + represents the role and extends the interface to the wl_surface. + If such a new protocol object is created, clients are + recommended to destroy it before they destroy the wl_surface. + Whether destroying the wl_surface first is legal, depends on the + protocol interface related to the role. </description> <enum name="error"> -- 1.8.5.5 _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel