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

[Pekka Paalanen]

On Tue, 19 Aug 2014 10:29:21 +0300
Pekka Paalanen <ppaalanen at gmail.com> wrote:

> 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

Bah... forgot to save one tiny change:

"Surface roles are given by ..."
-------------------^^^^^

Thanks,
pq

> +      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">