From ff2df60b1a07c3d26d170e65cd5440d15cdf3088 Mon Sep 17 00:00:00 2001 From: Pekka Paalanen Date: Mon, 18 Aug 2014 17:07:34 +0300 Subject: [PATCH] protocol: define the concept of wl_surface role 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. v2: give more concrete examples of roles, define losing a role, Jasper rewrote the paragraph on how a role is set. v3: make role permanent, there is no such thing as "losing a role". Re-issuing the same role again must be allowed for wl_pointer.set_cursor et al. to work. v4: clarify the semantics of destroying a role object. Signed-off-by: Pekka Paalanen Reviewed-by: Jason Ekstrand --- protocol/wayland.xml | 33 +++++++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/protocol/wayland.xml b/protocol/wayland.xml index bb457bc..621c64d 100644 --- a/protocol/wayland.xml +++ b/protocol/wayland.xml @@ -973,8 +973,37 @@ 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 (as set by wl_pointer.set_cursor), a drag icon + (wl_data_device.start_drag), a sub-surface + (wl_subcompositor.get_subsurface), and a window as defined by a + shell protocol (e.g. wl_shell.get_shell_surface). + + A surface can have only one role at a time. Initially a + wl_surface does not have a role. Once a wl_surface is given a + role, it is set permanently for the whole lifetime of the + wl_surface object. Giving the current role again is allowed, + unless explicitly forbidden by the relevant interface + specification. + + Surface roles are given by requests in other interfaces such as + wl_pointer.set_cursor. The request should explicitly mention + that this request gives a role to a wl_surface. Often, this + request also creates a new protocol object that represents the + role and adds additional functionality to wl_surface. When a + client wants to destroy a wl_surface, they must destroy this 'role + object' before the wl_surface. + + Destroying the role object does not remove the role from the + wl_surface, but it may stop the wl_surface from "playing the role". + For instance, if a wl_subsurface object is destroyed, the wl_surface + it was created for will be unmapped and forget its position and + z-order. It is allowed to create a wl_subsurface for the same + wl_surface again, but it is not allowed to use the wl_surface as + a cursor (cursor is a different role than sub-surface, and role + switching is not allowed). -- 2.7.4