[PATCH wayland] 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.

Signed-off-by: Pekka Paalanen <pekka.paalanen at 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