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

[Pekka Paalanen]

On Wed, 20 Aug 2014 10:26:48 -0400
"Jasper St. Pierre" <jstpierre at mecheye.net> wrote:

> On Wed, Aug 20, 2014 at 7:09 AM, 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.
> >
> > 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.
> >
> > Signed-off-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> > ---
> >  protocol/wayland.xml | 27 +++++++++++++++++++++++++--
> >  1 file changed, 25 insertions(+), 2 deletions(-)
> >
> > diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> > index 2d57f69..7b05338 100644
> > --- a/protocol/wayland.xml
> > +++ b/protocol/wayland.xml
> > @@ -973,8 +973,31 @@
> >        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.
> >
> 
> This is an odd expression to use. I'd put it in quotes, and give a few
> examples.
> 
> 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,
> destroying the wl_subsurface object will hide the subsurface, but the
> object will still have the subsurface role. To re-show the subsurface, a
> new wl_subsurface object may be created on the same wl_surface.

Ok, I can add more explanation to it. I am going to avoid phrases like
"re-show", because the state is not preserved.

I think I'll start a new thread with a whole series including this
patch, and fixing the protocol spec for the other things in core wrt.
roles.

But I will need someone else to write me a weston implementation of
this, with a test that checks we actually get an error if role
switching is attempted, before this spec change can land. That is the
only way to check during the alpha period that we are not breaking apps
with this.

IOW, if we want this to be included in the alpha, I need to be able to
merge it on Friday. Unless there is a good reason to let the schedule
slip.


Thanks,
pq