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

[Pekka Paalanen]

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?

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


Thanks,
pq