[PATCH wayland v2] protocol: define the concept of wl_surface role

[Pekka Paalanen]

From: Pekka Paalanen <pekka.paalanen at 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.

v2: give more concrete examples of roles, define losing a role, Jasper
rewrote the paragraph on how a role is set.

Signed-off-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
---
 protocol/wayland.xml | 26 ++++++++++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 2d57f69..d3fcaec 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -973,8 +973,30 @@
       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 can never be given a different role again, even if the
+      wl_surface loses the role in between.
+
+      Surface roles are set 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.
+
+      A wl_surface may lose its role as specified in the interface
+      that gave it the role or in the interface of the role object.
+      Losing a role means losing all the role-specific state.
     </description>
 
     <enum name="error">
-- 
1.8.5.5