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

[Jonas Ådahl]

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