[PATCH wayland] protocol: Clarify semantics of sub-surface placement requests

[Jasper St. Pierre]

Hey,

This came up during the mutter implementation. See my questions here for
what prompted this. I found the proposed phrasing a bit confusing as well...

https://bugzilla.gnome.org/show_bug.cgi?id=705502#c16


On Fri, Jan 17, 2014 at 6:37 AM, Jonas Ådahl <jadahl at gmail.com> wrote:

> On Fri, Jan 17, 2014 at 12:20:17PM +0200, Pekka Paalanen wrote:
> > Hi Jonas
> >
> > On Thu, 16 Jan 2014 23:27:07 +0100
> > Jonas Ådahl <jadahl at gmail.com> wrote:
> >
> > > Clarify some semantics of wl_subsurface.place_below and
> > > wl_subsurface.place_below that were not specified.
> >
> > Below and below. ;-)
> >
> > >
> > > Signed-off-by: Jonas Ådahl <jadahl at gmail.com>
> > > ---
> > >
> > > Hi,
> > >
> > > Implementing support for sub-surfaces in mutter we ran in to some
> > > unspecified behaviour in the subsurface placement protocol.
> > >
> > > I have documented what I understand is how the implementation in weston
> > > works (please correct me if I'm wrong). Is this the intended semantics?
> > >
> > > Jonas
> > >
> > >  protocol/wayland.xml | 6 ++++++
> > >  1 file changed, 6 insertions(+)
> > >
> > > diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> > > index 61fde84..619567c 100644
> > > --- a/protocol/wayland.xml
> > > +++ b/protocol/wayland.xml
> > > @@ -1952,6 +1952,12 @@
> > >
> > >     A new sub-surface is initially added as the top-most in the stack
> > >     of its siblings and parent.
> > > +
> > > +   Between two sub-surface parent commits, the stacking of surfaces
> in a
> > > +   sub-surface tree are executed as operations in the same order as
> the
> > > +   requests were made. A placement request may alter two surfaces
> relative
> > > +   placement by placing itself in-between. A subsequent placement
> request
> > > +   to a sub-surface replaces any previous requests.
> > >        </description>
> > >
> > >        <arg name="sibling" type="object" interface="wl_surface"
> >
> > Hmm, I guess, but I am not sure I understand this description at all.
> >
> > The intention, and how the code works, is that each change is executed
> > in the order the place_above/below requests are sent, and each request
> > operates on the outcome of the previous. Whether there is a parent
> > commit in between or not makes no difference.
> >
> > The code has two lists: the effective ordering, and the pending
> > ordering. These requests directly affect the pending ordering as they
> > are received. When the parent surface is committed, the pending
> > ordering overwrites the effective ordering, making them equal. The
> > effective ordering is what is composited on screen.
> >
> > In essence, you can think of the place_above/below operating
> > immediately, and parent commits just publish the whole ordering.
> >
> > Does this help? Can you rephrase the protocol documentation?
>
> This is how I understood it, but I'll try to rephrase it some,
> given your explanation, and send a v2.
>
> >
> > What was the unspecified behaviour here? I'm not sure how else you
> > could understand place_above/below, but then again I'm the original
> > author so it's far too obvious to me. :-)
>
> For example one could queue the operations until commit, having a
> subsequent request replace a previous one, instead of executing
> them immediately relying on commit to take a snapshot.
>
> It could also be read as a subsequent request that now replaces a
> previous request to be invalid. This should also be clarified in
> set_position so I'll send a patch for that too.
>
> Thanks for the review!
>
>
> Jonas
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
>



-- 
  Jasper
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20140117/d57a3bef/attachment.html>