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 <pekka.paalanen@collabora.co.uk>
Reviewed-by: Jason Ekstrand <jason.ekstrand@intel.com>

1 files 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).
     </description>
 
     <enum name="error">