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

[Jason Ekstrand]

Pekka,
I have one nitpick below.  However, if we can't find a good solution, I'm
ok with pushing as-is.

Reviewed-by: Jason Ekstrand <jason.ekstrand at intel.com>


On Tue, Aug 19, 2014 at 1:41 AM, Pekka Paalanen <ppaalanen at gmail.com> wrote:

> 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.
>

I don't really like the term "looses its role".  Once a surface is a
"cursor surface" it is always a cursor surface, it just might not be the
*current* currsor surface.  How about:

"A surface can only have one role in its lifetime.  Even if the surface
stops being actively used in its role, it can never be used in any other
role.  For instance, once you call wl_pointer.set_cursor on a surface, the
surface is now a "cursor surface".  Even if it stops being the active
cursor, the wl_surface object retains the "cursor" role cannot be used in a
different role."

Thoughts?


> > +
> > +      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">
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20140819/e04de671/attachment.html>